Sign inGet Started

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

CampoSiempre presenteDescripción
typeSíCategoría general para ramificación gruesa: un enum cerrado (auth_error, validation_error, rate_limit_error, ...).
codeSíIdentificador opaco y estable que corresponde a E\d{5}. Único, nunca renombrado, nunca reutilizado; el valor canónico contra el cual comparar.
nameSíSlug legible (ValidationError) para facilitar la lectura de logs. Siempre acompañado de code, nunca un reemplazo de este.
messageSíDescripción legible. No es estable; muéstrala o regístrala en logs, nunca la parsees.
doc_urlSíEnlace estable a la página de documentación de este code.
request_idSíID de correlación, también devuelto como el encabezado de respuesta X-Request-Id. Inclúyelo en las solicitudes de soporte.
paramNoEl campo con el problema, cuando un solo campo es el causante.
detailsNoFallos 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_codeNoCó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.
EstadotypeSignificado
400bad_request_errorLa solicitud estaba mal formada: un cuerpo no parseable o un encabezado inválido (por ejemplo, un Idempotency-Key incorrecto).
401auth_errorLa solicitud contenía credenciales ausentes, inválidas o revocadas. Consulta Autenticación.
402billing_errorLa solicitud requiere un método de pago, saldo o plan que la organización no tiene. Consulta Facturación y uso.
403permission_errorLas credenciales son válidas, pero no tienen permiso para realizar esta solicitud. Consulta Autenticación.
404not_found_errorNinguna ruta coincide con esta ruta, o el recurso no existe en este espacio de trabajo. Consulta Regiones.
409conflict_errorLa solicitud entra en conflicto con el estado actual del recurso, incluidos conflictos de idempotencia (E01004, E01005). Consulta Idempotencia.
410gone_errorEl recurso existió, pero fue eliminado permanentemente.
412precondition_errorNo se cumplió una precondición para esta solicitud.
413payload_too_large_errorEl cuerpo de la solicitud excede el tamaño máximo permitido.
421misdirected_errorLa solicitud llegó a una región que no puede atenderla. Consulta Regiones.
422delivery_errorEl mensaje fue aceptado como solicitud, pero no puede entregarse a la dirección indicada.
422validation_errorEl cuerpo de la solicitud se parseó correctamente, pero uno o más valores son inválidos.
425too_early_errorLa solicitud llegó antes de que pueda ser procesada.
429rate_limit_errorSe agotó un grupo de limitación de solicitudes para este espacio de trabajo. Consulta Límites de solicitudes.
499client_closed_request_errorLa conexión se cerró antes de que la respuesta estuviera lista, normalmente porque el cliente dejó de esperar.
500internal_errorAlgo falló de nuestro lado al procesar la solicitud. Consulta Idempotency.
501not_implemented_errorEl endpoint está declarado en API pero aún no está implementado.
503service_unavailable_errorAlgo 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;
}

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ÁreaCódigos
E01xxxInfraestructura30 códigos, 2 retirados
E02xxxAuth e identidad9 códigos, 2 retirados
E03xxxFacturación y planes12 códigos
E04xxxEnvío y entrega de email67 códigos, 3 retirados
E05xxxDominios y DNS19 códigos
E06xxxWebhooks7 códigos
E07xxxWallet4 códigos
E10xxxCuotas9 códigos, 2 retirados
E11xxxPools de IP e IPs dedicadas4 códigos, 1 retirado
E12xxxEnvío y entrega de SMS49 códigos, 5 retirados
E13xxxVerify7 códigos, 1 retirado
E14xxxNúmeros5 códigos
E15xxxEnvío y entrega de WhatsApp49 códigos
E16xxxTrust1 código
E17xxxBuzones de agente14 códigos, 2 retirados
E19xxxCumplimiento de registro4 códigos
E21xxxVoz y troncalización SIP16 códigos, 7 retirados
E22xxxConsulta de números4 códigos
E23xxxRealtime1 código
E24xxxCompetitive Insights6 códigos
E25xxxSendability5 códigos, 1 retirado
E27xxxInbox Insights5 códigos
E28xxxApple Messages for Business18 códigos, 2 retirados
E32xxxConfirmación de operaciones6 códigos

Relacionado