Errors

The API uses ordinary HTTP status codes. Every 4xx error body is JSON with a detail:

{ "detail": "api key lacks the leads:write scope" }

Request validation errors (422) carry a list instead, one entry per problem, with where it is:

{
  "detail": [
    { "type": "missing", "loc": ["body", "person", "name"], "msg": "Field required", "input": {} }
  ]
}

Status codes

• 200 OK / 201 Created / 202 Accepted / 204 No Content — success. Ingestion answers 201 for a new Lead and 200 for a matched one.
• 400 Bad Request — a malformed header, e.g. an Idempotency-Key longer than 255 characters.
• 401 Unauthorized — no API Key, or one that is unknown, expired or revoked.
• 402 Payment Required — the subscription is read-only, so writes are refused. Reads, and ingestion, still work.
• 403 Forbidden — the key lacks the scope the operation needs.
• 404 Not Found — nothing with that id in your account.
• 409 Conflict — a request with the same Idempotency-Key is still running; retry shortly.
• 422 Unprocessable Content — the request is invalid (a missing field, a bad cursor, a webhook URL that is not public https), or an Idempotency-Key was reused for a different request.
• 429 Too Many Requests — a rate budget is spent; wait Retry-After seconds.
• 500 Internal Server Error — our fault; the body is plain text. Retry with the same Idempotency-Key.
• 503 Service Unavailable — the account is suspended.

What to retry

Retry 429, 409, 500, 502, 503, 504 and network errors, with exponential backoff, and always send an Idempotency-Key on POSTs so a retry is safe. Don't retry other 4xx answers without changing the request.

Every operation's possible answers are listed in the API reference.