Errors

Every error has the same body:

{
  "statusCode": 403,
  "code": "API_KEY_SCOPE_INSUFFICIENT",
  "message": "This key lacks WRITE_LEADS",
  "timestamp": "2026-10-01T09:30:00.000Z",
  "path": "/v1/leads",
  "requestId": "6f1c..."
}

Branch on code, not on message. Messages are written for people and can change. message is an array when a request fails several validations at once. Quote the requestId when you contact support.

Status codes

Status	Meaning	Retry?
`400`	Malformed or invalid request (`VALIDATION_RULE_FAILED`, `STAGE_REQUIREMENTS_NOT_MET`, `IDEMPOTENCY_KEY_INVALID`, …)	No. Fix the request
`401`	Missing, invalid, expired or revoked credentials	No. Fix the credential
`403`	Authenticated but not allowed: scope, plan, Profile, IP allow-list, field-level security	No
`404`	Not found, or not visible to you. The two are indistinguishable on purpose	No
`409`	Idempotency conflict, or a state conflict	See idempotency
`413`	Payload too large for the endpoint	No. Send less
`423`	The record is locked while an approval is pending (`RECORD_LOCKED`)	After the approval completes
`429`	Rate limited	Yes, after `Retry-After` seconds
`500`	Unexpected error	Safe reads: yes, with backoff. Writes: only with an `Idempotency-Key`
`503`	Temporarily unavailable; carries `Retry-After` unless the code says otherwise (for example `AI_UNAVAILABLE` when no AI provider is configured)	Yes, after `Retry-After`

Common codes

Code	Status	Meaning
`API_KEY_INVALID`	401	No such key
`API_KEY_EXPIRED`	401	Past its expiry, or past a rotation's overlap
`API_KEY_REVOKED`	401	Revoked
`API_KEY_OWNER_INACTIVE`	401	The key's owner is deactivated
`API_KEY_OWNER_NOT_IN_ORG`	401	The owner left the key's organization
`ORGANIZATION_SUSPENDED`	401	The key's organization is suspended
`API_KEY_IP_NOT_ALLOWED`	403	Request came from outside the key's IP allow-list
`API_KEY_SCOPE_INSUFFICIENT`	403	Key lacks the scope this route needs
`API_KEY_SCOPE_BLOCKED`	403	Route is never available to keys (`/auth`, `/api-keys`, `/admin`, … — see authentication)
`SESSION_REQUIRED`	403	Route needs a signed-in person, not a key or token
`API_KEY_RATE_LIMITED`	429	The key's own rate limit is spent
`API_KEY_AUTH_THROTTLED`	429	Too many failed key attempts from this IP
`FEATURE_ACCESS_DENIED`	403	Your plan doesn't include this feature
`FIELD_NOT_EDITABLE`	403	Your Profile can't edit a field you sent
`VALIDATION_RULE_FAILED`	400	An org validation rule rejected the save
`STAGE_REQUIREMENTS_NOT_MET`	400	Required fields for the target stage are missing (`missingFields` lists them)
`IDEMPOTENCY_KEY_REUSED`	409	Same `Idempotency-Key`, different request
`IDEMPOTENCY_REQUEST_IN_PROGRESS`	409	The original request is still running
`RECORD_LOCKED`	423	A pending approval locks the record
`BEFORE_SAVE_HOOK_REJECTED`	400	A before-save hook refused the save; `message` is the hook's
`BEFORE_SAVE_HOOK_UNAVAILABLE`	503	A fail-closed hook couldn't be reached
`COMPONENT_MANAGED_BY_APP`	409	An installed app manages this component

OAuth token errors use their own codes; see OAuth 2.0.

Status codes

Common codes

On this page