Errors

Every error carries a stable machine code, a human message and a request id. 95 codes are in use.

Shape

json

{
  "error": "INSUFFICIENT_SCOPE",
  "reason": "SCOPE_NOT_GRANTED",
  "message": "Your role does not allow this action.",
  "request_id": "req_01J..."
}

error is the contract — switch on it. reason is extra precision where the platform can give it. message is written for a person and is localised; never parse it. request_id also arrives as the x-request-id response header, on every response including ones with no body — quote it when you contact support.

Platform errors

These come from the transport layer and can appear on any endpoint.

Code	Status
`NOT_FOUND`	404, 409
`BAD_REQUEST`	400
`RATE_LIMITED`	429
`UNAUTHORIZED`	401
`FORBIDDEN`	403
`IDEMPOTENCY_IN_PROGRESS`	409
`IDEMPOTENCY_KEY_REUSED`	409
`VALIDATION_ERROR`	400

Domain errors

This list is extracted from the source, not curated by hand — which is why it is complete and also why it is flat. A code appears here if some endpoint can return it; which endpoints, and when, is in that endpoint's own reference entry.

Code	Status	Sites
`LIMIT_REACHED`	403, 409, 422	7
`INVALID_FLOW`	400	6
`CONFLICT`	409	5
`DUPLICATE_NAME`	409	4
`INCOMPLETE_ONBOARDING`	422	3
`INVALID_CODE`	400	3
`RATE_LIMIT`	429	3
`UPLOAD_ERROR`	500	3
`ACKNOWLEDGEMENT_REQUIRED`	428	2
`AGENT_HAS_CHANNELS`	409	2
`ATTACHMENT_FAILED`	502	2
`AUDIO_TOO_LARGE`	413	2
`CHANNEL_ASSET_INCOMPATIBLE`	400	2
`CHUNK_LIMIT_REACHED`	409	2
`EMAIL_IN_USE`	409	2
`FEATURE_NOT_AVAILABLE`	403	2
`FILE_TOO_LARGE`	413	2
`INTERNAL_STEP_NOT_ALLOWED`	400	2
`INVALID_OFFER`	400	2
`INVALID_WEBHOOK_SIGNATURE`	401	2
`STALE_WRITE`	412	2
`TOO_MANY`	—	2
`TRANSCRIPTION_FAILED`	502	2
`UNSUPPORTED_AUDIO`	400	2
`UNSUPPORTED_FILE`	400	2
`WEBHOOK_NOT_CONFIGURED`	503	2
`AGENT_HAS_DATA`	409	1
`ALREADY_CLASSIFIED`	409	1
`ALREADY_VERIFIED`	409	1
`ASSIGNEE_NOT_IN_TEAM`	422	1
`BASE_HAS_SOURCES`	409	1
`BASE_IS_DEFAULT`	409	1
`BASE_NOT_IN_TEAM`	422	1
`BOUNDARY_EVAL_REQUIRED`	409	1
`CANNOT_REVOKE_CURRENT`	409	1
`CODE_EXPIRED`	400	1
`CONNECTION_NOT_STARTED`	409	1
`DEFAULT_PIPELINE`	400	1
`DELETE_FAILED`	400	1
`DISCOUNT_ALREADY_USED`	409	1
`DRAFT_NOT_READY`	400	1
`DUPLICATE`	—	1
`DUPLICATE_SHORTCUT`	409	1
`EMAIL_ALREADY_VERIFIED`	400	1
`ENDPOINT_DISABLED`	409	1
`FAQ_LIMIT_REACHED`	400	1
`FLOW_INACTIVE`	400	1
`GOOGLE_AUTH_UNAVAILABLE`	—	1
`IMPLEMENTATION_ORDER_IN_PROGRESS`	409	1
`INVALID_CONFIG`	—	1
`INVALID_CSV`	400	1
`INVALID_FUNCTION`	400	1
`INVALID_GOOGLE_FLOW`	422	1
`INVALID_OPERATIONS`	400	1
`INVALID_ORDER`	400	1
`INVALID_PHONE`	400	1
`INVALID_POLICY`	400	1
`INVALID_REASON`	400	1
`INVALID_STATE`	409	1
`INVALID_WEBHOOK_URL`	422	1
`MARKETING_ATTESTATION_RATE_LIMITED`	429	1
`META_GRAPH_ERROR`	—	1
`METHOD_NOT_ALLOWED`	405	1
`NO_FUNCTION`	400	1
`NOT_REACTABLE`	400	1
`OFFER_NOT_DISCOUNT`	400	1
`OFFER_NOT_FOUND`	404	1
`PASSWORD_ALREADY_SET`	409	1
`PAYMENT_PROVIDER_UPDATE_REQUIRED`	400	1
`PAYMENT_REQUIRED`	400	1
`PLAN_FULL`	409	1
`QUOTA_EXCEEDED`	402	1
`REASSIGN_TO_SELF`	400	1
`RULES_TOO_LONG`	400	1
`SAME_EMAIL`	400	1
`SERVER_ONLY_EVENT`	400	1
`SLOT_OCCUPIED`	—	1
`STAGE_IN_USE`	409	1
`STAGE_NOT_EMPTY`	400	1
`TEXT_TOO_LONG`	400	1
`UNKNOWN_ACTION`	422	1
`VERIFICATION_EMAIL_FAILED`	400	1
`VOICE_QUOTA_EXCEEDED`	402	1
`VOICE_SYNTHESIS_FAILED`	503	1
`WEBHOOK_ENQUEUE_FAILED`	503	1
`WHATSAPP_CONNECTION_FAILED`	502	1
`WRONG_PROVIDER`	400	1

What to retry

Retry 429 (after Retry-After) and 5xx, with backoff. Never retry 4xx other than 429 — the request will fail the same way. For creations, retry with the same Idempotency-Key so the retry cannot duplicate.