Sign inGet Started

Limitación de solicitudes

Los límites de solicitudes definen cuántas peticiones puede hacer tu organización en una ventana de tiempo. Usa los encabezados de respuesta para regular el tráfico y el retraso de reintento para recuperarte de una solicitud rechazada.

Cómo se aplican los límites

Tu organización comparte un límite regional por cada política, entre todas sus claves API y espacios de trabajo. Crear otra clave no añade capacidad. Organizaciones distintas tienen límites independientes.
Cada solicitud consume una política de cliente. Las políticas de producto tienen capacidad independiente: consultar el estado de un mensaje no consume el límite general de obtención de recursos, y enviar un correo electrónico no consume el límite de creación de recursos.
Las operaciones de inicio de sesión, restablecimiento de contraseña y otras operaciones sensibles de seguridad tienen protecciones adicionales contra abuso. Las verificaciones del proveedor y los límites de conexión también pueden rechazar solicitudes de forma independiente a los límites de solicitudes de tu plan.

Grupos

Las operaciones API ordinarias usan estas políticas:
PolíticaOperaciones
api_getObtener un recurso
api_listListar o buscar en una colección
api_createCrear un recurso
api_updateActualizar o insertar un recurso
api_deleteEliminar un recurso
Las operaciones de producto usan una política con nombre en lugar de la política API ordinaria. Algunos ejemplos son email_send, email_batch, sms_send, whatsapp_send, lookup y message_status_read. Las políticas de lote cuentan solicitudes de envío; la cantidad de destinatarios del lote no consume unidades de política adicionales. Consulta envío de correo electrónico por lotes y envío por lotes de SMS para los límites de tamaño de lote.
El correo electrónico REST y el envío SMTP comparten la capacidad de email_send. Un envío SMTP DATA consume una unidad; la autenticación SMTP no. Si la política deniega un envío, el servidor devuelve un error temporal 452 4.3.1 con un retraso de reintento y no acepta el mensaje. Mantén el mensaje en cola y reintenta después de ese retraso.
Crear una difusión usa api_create; iniciar una difusión existente usa api_update. La entrega en segundo plano a sus destinatarios no consume email_send. Las asignaciones de envío y el ritmo de entrega son controles independientes.
La política voice_call limita la admisión de llamadas entrantes y salientes. Una política agotada rechaza la llamada y registra calls_per_second_exceeded; no interviene una respuesta HTTP. Consulta Llamadas rechazadas.

Cómo se resuelve tu límite

Una anulación activa de organización establece tu tasa efectiva. Sin anulación, se aplica el valor de tu plan activo; si el plan no tiene un valor para esa política, se aplica el valor predeterminado. Un plan o una anulación puede aumentar o reducir la tasa. La ventana de tiempo de la política permanece fija.
Lee tu cuota efectiva en el encabezado de respuesta RateLimit-Policy, que indica la clave de la política junto con la tasa y la ventana que se aplicaron a esa llamada. Si necesitas capacidad adicional, contacta a soporte con la clave de la política y el tráfico esperado.

Encabezados de respuesta

Las evaluaciones de limitación de solicitudes proporcionan dos encabezados en el formato IETF Structured Fields (RFC 9651):
Ejemplo de código
RateLimit-Policy: "email_send";q=1000;w=60
RateLimit: "email_send";r=842;t=35
EncabezadoSignificado
RateLimit-PolicyLa política que se aplica: q es la cuota (unidades máximas) y w es la ventana en segundos.
RateLimitTu estado actual: r es el número de unidades restantes y t son los segundos hasta que la ventana se reinicie.
La cadena entrecomillada nombra la política. En este ejemplo, la organización tiene un límite efectivo email_send de 1000 envíos por cada 60 segundos, con 842 restantes y 35 segundos hasta el reinicio.
Usa r y t para reducir el ritmo de solicitudes antes de recibir un 429. El valor de t es un retraso relativo en segundos, no una marca de tiempo Unix.

Cuando alcanzas un límite

Tu integración debe gestionar las respuestas 429 como parte de la operación normal. Como mínimo, respeta Retry-After y reintenta con retroceso exponencial. Un cliente que además regula su ritmo según los encabezados RateLimit en vivo (consulta Encabezados de respuesta) evita alcanzar el límite.
Una política de cliente agotada devuelve 429 Too Many Requests con Retry-After en segundos y encabezados de limitación de solicitudes que muestran r=0. Una protección independiente contra abuso o del proveedor puede devolver 429 incluso cuando tu política de cliente tiene capacidad restante. Sigue Retry-After para decidir cuándo reintentar; puede diferir del valor t de la política.
El cuerpo usa la respuesta de error estándar:
Ejemplo de código
{
  "error": {
    "type": "rate_limit_error",
    "code": "E01003",
    "name": "RateLimited",
    "message": "Too many requests. Please retry after the period indicated in the Retry-After header.",
    "doc_url": "https://bird.com/docs/api/errors/E01003",
    "request_id": "req_01ky7qavkff7qr88vadv6bv948"
  }
}
Decide según type: rate_limit_error. El mensaje legible puede cambiar. Lee la clave de la política y los tiempos de reintento en los encabezados:
async function sendWithBackoff(url, headers, payload, maxAttempts = 5) {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    const response = await fetch(url, {
      method: "POST",
      headers,
      body: JSON.stringify(payload),
    });
    if (response.status !== 429) return response;
    const retryAfter = Number(response.headers.get("Retry-After") ?? 2 ** attempt);
    await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
  }
  throw new Error("rate limited after max retries");
}
Para reintentos de la misma operación, reutiliza su clave de idempotencia. Mantén el cuerpo de la solicitud sin cambios.
Consulta conceptos de SDK para el comportamiento de reintento automático y retroceso exponencial.

Modo de fallo

El limitador de solicitudes falla abierto: si Bird no puede evaluar un límite, la solicitud continúa en lugar de recibir un rechazo espurio. La limitación de solicitudes protege la capacidad del servicio. La autenticación y la autorización siguen siendo los límites de seguridad. Una caída del limitador en el lado Bird no provoca un 429.

Próximos pasos

  • Errores: la respuesta de error y cómo decidir según los tipos de error
  • Idempotencia: reintentos seguros para solicitudes de escritura
  • Conceptos de SDK: comportamiento de reintento automático y retroceso exponencial