Un emisor con mucha actividad puede agotar su presupuesto de solicitudes antes de que todos sus mensajes estén en cola. Leer la cuota restante le permite reducir el ritmo antes de que se rechacen más llamadas.
¿Cómo decide Bird mi límite?
Bird aplica una tasa base, cualquier incremento del plan y luego cualquier override para el grupo correspondiente. Un override reemplaza los demás valores.
Los endpoints relacionados comparten un grupo. Agotar un grupo de envío no agota por sí solo los grupos separados que se usan para leer estado o gestionar webhooks.
El alcance de cada presupuesto depende de la operación:
| Grupo | ¿Quién comparte el presupuesto? |
|---|---|
| Envíos de producto | Todas las credenciales de la organización para ese producto. |
| Lecturas, listados y escrituras de gestión | Solicitudes de la misma credencial activa dentro de la organización. |
| Inicio de sesión o restablecimiento de contraseña no autenticados | Solicitudes desde la misma IP del cliente. |
Los límites no autenticados usan umbrales fijos. Consulta la guía de límites de solicitudes para ver los grupos asignados a cada endpoint.
Los límites de envío cuentan solicitudes, no destinatarios. Una solicitud en lote puede encolar varios mensajes. Su grupo puede tener una cuota diferente.
Compara las cuotas activas y la cantidad de destinatarios que puedes agrupar antes de cambiar de endpoint. Un lote con un solo destinatario puede no aportar ninguna ganancia de rendimiento.
¿Cómo leo los encabezados de respuesta?
Lee RateLimit-Policy para la cuota y la ventana, y luego RateLimit para las solicitudes restantes y el tiempo hasta el reinicio.
Por ejemplo:
RateLimit-Policy: "email_send";q=1000;w=60
RateLimit: "email_send";r=842;t=35Este ejemplo permite 1.000 solicitudes en una ventana de 60 segundos. Quedan 842 solicitudes, con 35 segundos hasta el reinicio.
Los números ilustran los encabezados. No son una cuota garantizada. Lee los valores que recibe tu cliente.
| Campo | Significado |
|---|---|
| Nombre citado | El grupo al que aplica la política. |
q | Solicitudes permitidas por ventana. |
w | Duración de la ventana en segundos. |
r | Solicitudes restantes. |
t | Segundos hasta el reinicio, no una marca de tiempo. |
Una respuesta puede incluir más de una política. Ten en cuenta todas las políticas aplicables al programar la siguiente solicitud.
¿Qué devuelve un fallo por limitación de solicitudes?
Un límite agotado de API devuelve 429 Too Many Requests con Retry-After en segundos. Los encabezados de limitación de solicitudes identifican el grupo agotado. Su cuota restante es r=0.
La respuesta de error incluye estos campos:
{
"error": {
"type": "rate_limit_error",
"code": "E01003",
"name": "RateLimited"
}
}Haz coincidir el type o el code en tu handler. El mensaje legible puede cambiar sin que cambie la acción de recuperación.
¿Cómo debe manejar mi cliente un 429?
Espera el valor de Retry-After y luego reintenta con una política de backoff limitada. Conserva la misma clave de idempotencia cuando repitas la misma escritura.
Coordina los workers que usan el mismo presupuesto de grupo. La última respuesta de un worker no puede reflejar las solicitudes que otros workers hayan enviado desde entonces.
Reduce el ritmo a medida que la cuota restante baja. Conserva la ruta de reintento para tráfico concurrente. Regular el ritmo reduce los fallos, pero no garantiza que ninguna llamada reciba un 429.
Los SDKs de Bird gestionan los reintentos de 429 y Retry-After. No coordinan una cola compartida entre todos tus procesos.
Si la cuota sigue siendo demasiado baja para la carga de trabajo, contacta con Bird para solicitar un override. Crear más claves no aumenta el límite de envío a nivel de organización.
¿Ha realizado algún trabajo una solicitud limitada?
Bird rechaza una solicitud limitada antes de ejecutar el trabajo solicitado. Ese rechazo no consume su clave de idempotencia. Reintenta con la misma clave después de esperar.
El limitador deja pasar las solicitudes si no puede evaluar el límite. Un problema al evaluar las cuotas, por tanto, no produce por sí solo un 429.
Conserva el manejo de idempotencia también para otros fallos. Un error del servidor o una respuesta perdida pueden ocurrir después de que una escritura haya comenzado.
En resumen
Lee la cuota en las respuestas.
El límite aplicable depende del grupo, el plan y cualquier override. Un número fijo puede volverse incorrecto.
Coordina los emisores que comparten una cuota.
Los límites de envío se aplican a toda la organización, así que claves separadas no crean presupuestos de envío separados.
Espera antes de reintentar un 429.
Retry-Afterindica la demora en segundos. Limita tus reintentos. Conserva la clave de idempotencia para la misma escritura.Trata los encabezados como estado compartido.
Las solicitudes restantes pueden ser consumidas por otros workers, así que regular el ritmo reduce los fallos por limitación de solicitudes sin eliminarlos.