Errores

Toda solicitud API fallida de Bird devuelve la misma respuesta de error JSON, anidada bajo una clave de nivel superior error. Esta es una respuesta real a una solicitud de envío con cuerpo vacío:

Ejemplo de código

{
  "error": {
    "type": "validation_error",
    "code": "E01001",
    "name": "ValidationError",
    "message": "Request has 1 validation error.",
    "doc_url": "https://bird.com/docs/api/errors/E01001",
    "request_id": "req_01ky7q3hckecgv6d7jpq865532",
    "details": [{ "param": "body", "message": "missing properties 'from', 'to'" }]
  }
}

El estado HTTP se deriva del type. Los errores del cliente usan 400 para solicitudes mal formadas, 401 o 403 para fallos de acceso, 402 para facturación y 404 para recursos inexistentes. Usan 409 para conflictos, 412 para precondiciones no cumplidas, 422 para fallos de validación y reglas de negocio, y 429 para limitación de solicitudes. Los fallos del lado Bird usan 5xx. El estado identifica la categoría; la respuesta de error explica lo que ocurrió.

Campos de la respuesta de error

Campo	Función
type	Categoría general para ramificación gruesa: validation_error, auth_error, permission_error, not_found_error, conflict_error, rate_limit_error, billing_error, internal_error, y algunos otros. Un enum cerrado que crece raramente.
code	Identificador opaco y estable (E01001). La referencia canónica: único, nunca renombrado, nunca reutilizado. Cuando un error se retira, su código queda reservado permanentemente.
name	Slug legible por humanos (ValidationError) para facilitar la lectura de logs. Siempre acompaña a code, nunca lo reemplaza.
message	Descripción legible por humanos. No es estable: la redacción puede cambiar sin previo aviso. Muéstrala, regístrala, nunca la analices.
param	Para errores relacionados con la entrada, el campo que causó el problema. Se omite cuando no aplica.
doc_url	Enlace estable a la página de documentación de este código.
request_id	Siempre presente, y también devuelto como encabezado de respuesta X-Request-Id. Inclúyelo en las solicitudes de soporte; permite a Bird rastrear la solicitud exacta.
details	Problemas de validación por campo. Presente solo en respuestas validation_error.
remediation	Un siguiente paso legible por humanos para resolver el error. Presente cuando se conoce una recuperación.
next	Operaciones que resuelven el error, en el orden en que debes probarlas. Presente para errores con una recuperación bien definida, como precondiciones no cumplidas.
vendor_code	Código literal de un sistema externo (un código de respuesta SMTP, un código de rechazo de pago). Presente solo cuando Bird expone el código de un sistema externo sobre el que podrías querer actuar.

Ramifica según type para manejo grueso y code para manejo específico, nunca según message. Un cliente típico evalúa type (reintentar en rate_limit_error, mostrar validation_error al usuario, alertar a alguien en internal_error) y solo compara valores individuales de code para los pocos errores que maneja de forma especial.

Códigos como E04012 son intencionalmente opacos. Cada código enlaza a una página de documentación a través de doc_url, que explica la causa y cómo resolverlo. El catálogo completo está en la referencia de errores.

Fallos de validación: un código, muchos detalles

La validación por campo no genera un código separado por cada combinación de campo y fallo. Cada fallo de validación es E01001 ValidationError con un array details que lista cada problema por campo como {param, message}, del mismo modo que el fallo de envío capturado lista sus propiedades faltantes. Las cadenas message dentro de details pueden cambiar y solo deben mostrarse. Usa param para asociar problemas con campos de formulario.

Guía de recuperación: remediación y siguiente paso

Los errores con una solución conocida la incluyen en la respuesta de error. Esta es una respuesta real a una llamada de webhooks hecha con una clave API que carece del alcance requerido:

Ejemplo de código

{
  "error": {
    "type": "permission_error",
    "code": "E02035",
    "name": "InsufficientScope",
    "message": "This request requires the \"webhooks:read\" scope, which your credential has not been granted.",
    "param": "webhooks:read",
    "doc_url": "https://bird.com/docs/api/errors/E02035",
    "request_id": "req_01ky7q4665emc9tw1pxkptaqwq",
    "remediation": "Re-authenticate with a credential that has been granted the required scope, then retry."
  }
}

remediation es una oración para un humano o un log de agente; next, cuando está presente, lista las operaciones API que resuelven el error en el orden en que debes probarlas (verificar un dominio, luego reintentar el envío). Los agentes y CLIs pueden ejecutar next directamente; los clientes interactivos pueden mostrar remediation tal cual.

Manejar errores correctamente

Reintenta 429 y 5xx, nada más por defecto. Respeta Retry-After en la limitación de solicitudes (consulta Limitación de solicitudes), usa retroceso exponencial en 5xx y envía un Idempotency-Key para que los reintentos de solicitudes mutantes sean seguros.
Registra code, name y request_id juntos. El código es lo que buscarás en la documentación y en tus propios logs; el ID de solicitud es lo que soporte necesita.
Tolera códigos y tipos nuevos. Los códigos de error nuevos aparecen con regularidad a medida que los productos crecen, y el enum type ocasionalmente gana un valor. Escribe tu handler con una rama por defecto razonable en lugar de una coincidencia exhaustiva.

Siguientes pasos

Referencia de errores: el catálogo completo de errores, una página por código
Idempotencia: reintentos seguros para solicitudes mutantes
Limitación de solicitudes: encabezados de límite y guía de retroceso

Recursos relacionados

Continúa con la documentación, guías y ejemplos sobre este tema. Los recursos están en inglés.

Comprender el conceptoShould I use a Bird SDK or call the API directly?Seguir la ruta de aprendizajeBuild your first integration Guía de implementaciónSend your first email

Obtener un resumen de implementación