Errors reference

Every error response uses the same envelope. Branch on the code: it is a stable part of the contract. A code is never renamed or removed without a major version change; new codes are additive.

{
  "code": "VALIDATION_ERROR",
  "message": "phone_number must be a valid E.164 number.",
  "request_id": "b3f1c8d2-2b9e-4c5e-8a1f-2c7d6a9e4b1a",
  "details": { "field": "phone_number" }
}

message is human-readable and may change. request_id (also in the X-Request-Id header) identifies the request for support. details is optional and depends on the code.

Authentication (401)

Code	When
AUTH_MISSING_API_KEY	No x-api-key header was sent.
AUTH_INVALID_API_KEY	The key does not match any active key.
AUTH_REVOKED_API_KEY	The key was revoked.
AUTH_EXPIRED_API_KEY	The key passed its expiry date.

Authorization (403)

Code	When
AUTHORIZATION_FORBIDDEN	The key is valid but not allowed to perform this action.

Validation (400)

Code	When
VALIDATION_ERROR	The request body or query is malformed. details.field points at the offending field when it can be isolated.

Resources (404 / 409)

Code	Status	When
RESOURCE_NOT_FOUND	404	The referenced resource does not exist.
RESOURCE_CONFLICT	409	The request conflicts with the current state of the resource.

Idempotency (400 / 409)

Code	Status	When
IDEMPOTENCY_KEY_REQUIRED	400	The endpoint requires an Idempotency-Key header and none was sent.
IDEMPOTENCY_KEY_INVALID	400	The Idempotency-Key is malformed.
IDEMPOTENCY_CONFLICT	409	The same key was reused with a different request body.
IDEMPOTENCY_IN_PROGRESS	409	A request with the same key is still being processed. Retry shortly.

The Idempotency-Key header is optional on every endpoint today, so IDEMPOTENCY_KEY_REQUIRED is reserved for any future endpoint that opts into requiring it. See the idempotency guide for the full semantics.

Rate limiting (429)

Code	When
RATE_LIMIT_EXCEEDED	You exceeded the per-organization rate limit. Back off and retry.

Request format (413 / 415)

Code	Status	When
PAYLOAD_TOO_LARGE	413	The request body exceeds the size limit.
UNSUPPORTED_MEDIA_TYPE	415	The Content-Type is not application/json.

Server (500)

Code	When
INTERNAL_ERROR	An unexpected server-side failure. Safe to retry with back-off. Quote the request_id if it persists.