Skip to main content
Every error has a consistent JSON shape:
Every error.code maps to exactly one HTTP status, but a status can carry more than one code — 403 is both FORBIDDEN and PLAN_LIMIT_REACHED. Switch on code, not on the status, and surface message to your end user.

Codes

Plan-limit errors

A plan limit is not a permission problem, but it arrives on the same status code. Match on error.code, not on the status:
PLAN_LIMIT_REACHED was added so that “your plan is full” stops being indistinguishable from “your key lacks the scope” — both used to arrive as a bare 403 FORBIDDEN. The status code did not change, so existing clients that only check for 403 keep working. The other two endpoints still return FORBIDDEN and will move to a code of their own in a later release.
Plan-limit errors carry a message that may be localized to the organization’s language, such as “You have reached the maximum number of leads for your plan.” — surface it to your end users as-is, since they’re the ones who can take action (upgrade or remove records). Retrying a PLAN_LIMIT_REACHED is pointless until the organization upgrades: the verdict cannot change on its own. Alert instead, and hold the payload if you cannot afford to lose it. A merge is never blocked by the lead limit — no lead is created, so no slot is consumed. An organization at its cap can still enrich the leads it already has.

Validation errors

VALIDATION_ERROR messages list every field that failed in path: reason form, joined by ; :
Parse the message if you need to surface field-level errors in your own UI, or just show the whole string.

Idempotency and retries

  • 5xx and 429 are safe to retry. Use exponential backoff capped at the Retry-After value when present.
  • 4xx (other than 429) means the request itself is wrong. Don’t retry without changing it.
  • POST /webhooks/subscriptions is idempotent when you pass external_id — see Create a subscription.
  • POST /leads is idempotent by contact identity: retrying with the same email or phone merges into the existing lead instead of creating a duplicate. Read outcome in the response to tell a create from a merge — see Deduplication and merge.
  • Other writes are not idempotent. Retrying them blindly creates duplicate records.