Errores

Vocabulario completo y qué hacer con cada uno.

Todos los errores comparten un mismo envoltorio. Bifurque siempre por code, nunca por el texto de message.

{
  "error": {
    "code": "courier_unavailable",
    "message": "El courier no se encuentra disponible temporalmente.",
    "request_id": "req_01...",
    "details": {}
  }
}

Incluya siempre el request_id al reportar un problema: es lo que nos permite encontrar la traza exacta.

Código	Qué hacer
`validation_error`	Corrija la petición. Reintentar sin cambios repetirá el error.
`unauthorized`	Revise la credencial. No reintente.
`forbidden`	A la credencial le falta el scope. No reintente.
`not_found`	El recurso no existe o pertenece a otra organización.
`conflict`	El estado actual no admite la operación.
`idempotency_conflict`	Reusó una clave con un cuerpo distinto. Es un bug del cliente.
`rate_limited`	Reintente respetando Retry-After.
`quota_exceeded`	Se agotó la cuota del plan. No reintente hasta el siguiente período.
`courier_auth_failed`	La cuenta del courier no autenticó. Requiere reautorización.
`courier_action_required`	El cliente debe reautorizar su conexión. No reintente.
`courier_rejected`	El courier rechazó los datos. Corrija y vuelva a enviar.
`courier_unavailable`	Caída transitoria. Reintente con backoff y la MISMA clave.
`courier_timeout`	No reintente a ciegas: puede existir una guía. Consulte la operación.
`capability_unavailable`	La capacidad no está verificada para esta conexión. No reintente.
`document_unavailable`	El documento aún no existe. Reintente más tarde.
`operation_in_progress`	Hay una operación en curso. Consulte su estado antes de actuar.
`internal_error`	Error nuestro. Reintente con backoff; si persiste, comparta el request_id.

Nunca exponemos stack traces, mensajes internos ni respuestas HTML del courier. Si recibe un internal_error, el detalle está en nuestros logs bajo ese request_id.