Erros

Todo erro carrega um código estável de máquina, uma mensagem para pessoa e um id de requisição. 95 códigos estão em uso.

Forma

json

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

error é o contrato — decida em cima dele. reason é precisão extra onde a plataforma consegue dar. message é escrita para uma pessoa e é traduzida; nunca faça parsing dela. O request_id também chega no cabeçalho x-request-id, em toda resposta, inclusive nas que não têm corpo — cite ele ao falar com o suporte.

Erros de plataforma

Vêm da camada de transporte e podem aparecer em qualquer endpoint.

Código	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

Erros de domínio

Esta lista é extraída do código-fonte, não curada à mão — que é por que ela é completa e também por que ela é plana. Um código aparece aqui se algum endpoint pode devolvê-lo; quais endpoints, e quando, está na entrada de referência de cada um.

Código	Status	Ocorrências
`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

O que retentar

Retente 429 (depois do Retry-After) e 5xx, com recuo. Nunca retente 4xx fora o 429 — a requisição vai falhar do mesmo jeito. Em criações, retente com a mesma Idempotency-Key, para a retentativa não ter como duplicar.