Errors

Every error has a consistent JSON shape:

{
  "error": {
    "message": "Human-readable explanation, sometimes localized to the org's language.",
    "code": "MACHINE_READABLE_CODE"
  }
}

The HTTP status and the error.code are always consistent. Switch on code, surface message to your end user.

Codes

HTTP	`error.code`	Meaning
`400`	`BAD_REQUEST`	Generic client error.
`400`	`VALIDATION_ERROR`	Request body or query failed validation. The `message` lists the offending fields.
`401`	`UNAUTHORIZED`	Bearer missing, malformed, unknown, or expired.
`403`	`FORBIDDEN`	Authenticated but not permitted: missing scope, plan limit reached, inactive key, or business rule violation.
`404`	`NOT_FOUND`	Resource does not exist or is in a different organization.
`429`	`BAD_REQUEST`	Rate limit exceeded. Retry after `Retry-After` seconds. See Rate limits.
`500`	`INTERNAL_ERROR`	Unexpected server failure. Safe to retry idempotently after a short backoff.

Plan-limit errors

Plan-limit FORBIDDEN errors carry a localized message 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). These come from the billing guards on:

POST /leads — when maxLeads is exceeded.
POST /projects — when maxProjects is exceeded.
POST /webhooks/subscriptions — when maxWebhookEndpoints is exceeded.

Validation errors

VALIDATION_ERROR messages list every field that failed in path: reason form, joined by ; :

{
  "error": {
    "message": "Validation error: email: Invalid email; phone: String must be at most 50 characters",
    "code": "VALIDATION_ERROR"
  }
}

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.
Other writes are not idempotent. If you retry a POST /leads blindly, you’ll create duplicates. Use Search a lead first to de-dupe.

Get Started

Core concepts

Webhooks

Reference

Codes

Plan-limit errors

Validation errors

Idempotency and retries

​Codes

​Plan-limit errors

​Validation errors

​Idempotency and retries

Codes

Plan-limit errors

Validation errors

Idempotency and retries