Respuestas de error
Toda solicitud fallida devuelve la misma respuesta de error JSON bajo una clave de nivel superior error, con un estado HTTP que indica la categoría general. Esta página es el contrato de respuesta; para orientación sobre ramificación, reintentos y la filosofía del catálogo de códigos, consulta Errores.
Ejemplo de código
{
"error": {
"type": "validation_error",
"code": "E01001",
"name": "ValidationError",
"message": "Request validation failed.",
"doc_url": "https://bird.com/docs/api/errors/E01001",
"request_id": "req_01krdgeqcxet5s7t44vh8rt9mg",
"details": [
{ "param": "contact_id", "message": "this field is reserved and not yet supported" },
{ "param": "topic_id", "message": "this field is reserved and not yet supported" }
]
}
}Campos de la respuesta de error
| Campo | Siempre presente | Descripción |
|---|---|---|
| type | Sí | Categoría general para ramificación gruesa: un enum cerrado (auth_error, validation_error, rate_limit_error, ...). |
| code | Sí | Identificador opaco y estable que corresponde a E\d{5}. Único, nunca renombrado, nunca reutilizado; el valor canónico contra el cual comparar. |
| name | Sí | Slug legible (ValidationError) para facilitar la lectura de logs. Siempre acompañado de code, nunca un reemplazo de este. |
| message | Sí | Descripción legible. No es estable; muéstrala o regístrala en logs, nunca la parsees. |
| doc_url | Sí | Enlace estable a la página de documentación de este code. |
| request_id | Sí | ID de correlación, también devuelto como el encabezado de respuesta X-Request-Id. Inclúyelo en las solicitudes de soporte. |
| param | No | El campo con el problema, cuando un solo campo es el causante. |
| details | No | Fallos de validación por campo como objetos {param, message}, donde param es una ruta con puntos como to[0].email. Presente solo en respuestas validation_error. |
| vendor_code | No | Código literal de un sistema externo (un código de respuesta SMTP, un código de rechazo de pago) cuando vale la pena actuar sobre él. |
Mapeo de estado HTTP
Cada type corresponde a exactamente un estado HTTP, de modo que el estado y la respuesta de error nunca se contradicen.
| Estado | type | Significado |
|---|---|---|
| 400 | bad_request_error | La solicitud estaba mal formada: un cuerpo no parseable o un encabezado inválido (por ejemplo, un Idempotency-Key incorrecto). |
| 401 | auth_error | La solicitud contenía credenciales ausentes, inválidas o revocadas. Consulta Autenticación. |
| 402 | billing_error | La solicitud requiere un método de pago, saldo o plan que la organización no tiene. Consulta Facturación y uso. |
| 403 | permission_error | Las credenciales son válidas, pero no tienen permiso para realizar esta solicitud. Consulta Autenticación. |
| 404 | not_found_error | Ninguna ruta coincide con esta ruta, o el recurso no existe en este espacio de trabajo. Consulta Regiones. |
| 409 | conflict_error | La solicitud entra en conflicto con el estado actual del recurso, incluidos conflictos de idempotencia (E01004, E01005). Consulta Idempotencia. |
| 410 | gone_error | El recurso existió, pero fue eliminado permanentemente. |
| 412 | precondition_error | No se cumplió una precondición para esta solicitud. |
| 413 | payload_too_large_error | El cuerpo de la solicitud excede el tamaño máximo permitido. |
| 421 | misdirected_error | La solicitud llegó a una región que no puede atenderla. Consulta Regiones. |
| 422 | delivery_error | El mensaje fue aceptado como solicitud, pero no puede entregarse a la dirección indicada. |
| 422 | validation_error | El cuerpo de la solicitud se parseó correctamente, pero uno o más valores son inválidos. |
| 425 | too_early_error | La solicitud llegó antes de que pueda ser procesada. |
| 429 | rate_limit_error | Se agotó un grupo de limitación de solicitudes para este espacio de trabajo. Consulta Límites de solicitudes. |
| 499 | client_closed_request_error | La conexión se cerró antes de que la respuesta estuviera lista, normalmente porque el cliente dejó de esperar. |
| 500 | internal_error | Algo falló de nuestro lado al procesar la solicitud. Consulta Idempotency. |
| 501 | not_implemented_error | El endpoint está declarado en API pero aún no está implementado. |
| 503 | service_unavailable_error | Algo de lo que depende esta solicitud no está disponible temporalmente. |
Manejo de errores en los SDK
Cada SDK mapea la respuesta de error al modelo de errores nativo de su lenguaje y lleva todos los campos de la respuesta (type, code, message, doc_url, request_id, ...) en el valor de error.
import { BirdRateLimitError, BirdValidationError, BirdAPIError } from "@messagebird/sdk";
try {
await bird.email.send({
from: { email: "onboarding@messagebird.dev", name: "Bird" },
to: ["delivered@messagebird.dev"],
subject: "Hello from Bird",
html: "<p>My first Bird email.</p>",
});
} catch (err) {
if (err instanceof BirdRateLimitError) console.log(`rate limited; retry in ${err.retryAfter}s`);
else if (err instanceof BirdValidationError) console.error(err.details);
else if (err instanceof BirdAPIError) console.error(err.code, err.requestId);
else throw err;
}from bird import APIStatusError, RateLimitError, ValidationError
try:
client.email.send(
from_={"email": "onboarding@messagebird.dev", "name": "Bird"},
to=["delivered@messagebird.dev"],
subject="Hello from Bird",
text="My first Bird email.",
)
except RateLimitError as err:
print("rate limited; retry after", err.retry_after)
except ValidationError as err:
print(err.status_code, err.details)
except APIStatusError as err:
print(err.status_code, err.code, err.request_id)if err != nil {
var rle *bird.RateLimitError
var ve *bird.ValidationError
var ae *bird.APIError
switch {
case errors.As(err, &rle):
fmt.Println("rate limited; retry after", rle.RetryAfter)
case errors.As(err, &ve):
for _, d := range ve.Details {
fmt.Printf("%s: %s\n", d.Param, d.Message)
}
case errors.As(err, &ae):
fmt.Printf("API error %s (status %d, request %s)\n", ae.Code, ae.StatusCode, ae.RequestID)
default:
log.Print(err) // transport: *bird.ConnectionError or *bird.TimeoutError
}
}try {
$bird->email->send(
from: 'Bird <onboarding@messagebird.dev>',
to: ['delivered@messagebird.dev'],
subject: 'Hello from Bird',
html: '<p>My first Bird email.</p>',
);
} catch (ApiException $e) {
// The server returned an error response. $status is the HTTP status, $type
// the coarse category, $errorCode the stable E##### code.
echo $e->status, ' ', $e->errorCode ?? $e->type ?? 'error';
} catch (ConnectionException $e) {
// All retry attempts failed, so no HTTP response is available.
echo 'transport error: ', $e->getMessage();
}Catálogo de errores
Todos los códigos de error que devuelve la Bird API pública, divididos en una página por rango de códigos. Cada página de rango lista sus códigos, y cada código tiene su propia página con la causa y qué hacer. El doc_url en cualquier respuesta de error enlaza directamente a la página de ese código.
| Rango | Área | Códigos |
|---|---|---|
| E01xxx | Infraestructura | 30 códigos, 2 retirados |
| E02xxx | Auth e identidad | 9 códigos, 2 retirados |
| E03xxx | Facturación y planes | 12 códigos |
| E04xxx | Envío y entrega de email | 67 códigos, 3 retirados |
| E05xxx | Dominios y DNS | 19 códigos |
| E06xxx | Webhooks | 7 códigos |
| E07xxx | Wallet | 4 códigos |
| E10xxx | Cuotas | 9 códigos, 2 retirados |
| E11xxx | Pools de IP e IPs dedicadas | 4 códigos, 1 retirado |
| E12xxx | Envío y entrega de SMS | 49 códigos, 5 retirados |
| E13xxx | Verify | 7 códigos, 1 retirado |
| E14xxx | Números | 5 códigos |
| E15xxx | Envío y entrega de WhatsApp | 49 códigos |
| E16xxx | Trust | 1 código |
| E17xxx | Buzones de agente | 14 códigos, 2 retirados |
| E19xxx | Cumplimiento de registro | 4 códigos |
| E21xxx | Voz y troncalización SIP | 16 códigos, 7 retirados |
| E22xxx | Consulta de números | 4 códigos |
| E23xxx | Realtime | 1 código |
| E24xxx | Competitive Insights | 6 códigos |
| E25xxx | Sendability | 5 códigos, 1 retirado |
| E27xxx | Inbox Insights | 5 códigos |
| E28xxx | Apple Messages for Business | 18 códigos, 2 retirados |
| E32xxx | Confirmación de operaciones | 6 códigos |
Relacionado
- Conceptos de errores: estrategia de ramificación, detalles de validación y semántica de vendor_code
- Autenticación: credenciales detrás de 401 y 403
- Encabezado Idempotency-Key: los errores de conflicto 409 y reintentos seguros
- Límites de solicitudes: políticas, encabezados y manejo de 429
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 integrationGuía de implementaciónSend your first email
Obtener un resumen de implementación