Errores

Todo error lleva un código estable de máquina, un mensaje para personas y un id de petición. 95 códigos están en uso.

Forma

json

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

error es el contrato — decide sobre él. reason es precisión extra donde la plataforma puede darla. message está escrito para una persona y está traducido; nunca lo analices. El request_id también llega en la cabecera x-request-id, en toda respuesta, incluidas las que no tienen cuerpo — cítalo cuando contactes con soporte.

Errores de plataforma

Vienen de la capa de transporte y pueden aparecer en cualquier endpoint.

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

Errores de dominio

Esta lista se extrae del código fuente, no se cura a mano — por eso es completa y por eso también es plana. Un código aparece aquí si algún endpoint puede devolverlo; qué endpoints, y cuándo, está en la entrada de referencia de cada uno.

Código	Estado	Ocurrencias
`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

Qué reintentar

Reintenta 429 (tras el Retry-After) y 5xx, con espera creciente. Nunca reintentes un 4xx que no sea 429 — la petición fallará igual. En las creaciones, reintenta con la misma Idempotency-Key, para que el reintento no pueda duplicar.