Rate limits
Escriba el cliente contra las cabeceras, no contra un número
Los cupos varían por plan y cambian con el tiempo. La forma de la política no: lea las cabeceras, retroceda con desfase aleatorio y use la vía masiva para el trabajo masivo.
- Aplicado por
- Organización
- Señalado por
- Cabeceras de respuesta
- Resolución
- Contabilizado aparte
Definition
¿Cómo se aplican los límites de frecuencia de la API?
Los límites se aplican por organización y por clase de endpoint, y se comunican en cada respuesta mediante cabeceras que indican el límite, el cupo restante y la hora de reinicio. La resolución pública del pasaporte se contabiliza aparte de su cuota, porque una ráfaga de escaneos no debe consumir el presupuesto de una tubería de emisión.
A client written against the headers keeps working when a quota changes. A client written against a number from a documentation page does not, and fails at the least convenient moment.
Clases
No todos los endpoints se contabilizan igual
| Class | Example | How it is governed |
|---|---|---|
| Public resolution | A consumer scanning a data carrier | Caching and edge capacity, not your quota |
| Read | Fetching a passport or an object history | Account quota, generous, cache-friendly |
| Write | Issuing a passport, appending an event | Account quota, lower ceiling than read |
| Bulk | Back catalogue import, historic event backfill | Asynchronous job with its own concurrency limit |
| Credential operations | Issuing or verifying a signed claim | Metered separately; cryptographic work is not free |
Cabeceras
Qué le dice cada respuesta
RateLimit-Limit: the ceiling for this endpoint class
RateLimit-Remaining: what is left in the current window
RateLimit-Reset: seconds until the window resets
Retry-After: present on 429 — honour this first
# Back off with jitter. A fixed interval across many workers
# turns one brief limit into a sustained one.
const delay = Math.min(2 ** attempt * base, ceiling);
await sleep(delay * (0.5 + Math.random() / 2));Diseño del cliente
Qué hace un cliente bien educado
Lee las cabeceras
Se adapta al cupo vigente en lugar de suponer una cifra documentada.
Reintenta con desfase aleatorio
Retardo aleatorio, para que los trabajadores en paralelo no reintenten al unísono.
Usa la vía masiva
La carga del catálogo histórico va por el modo masivo, no por un bucle sobre un endpoint de recurso único.
Separa las tuberías
Emisión y reporte con claves distintas, de modo que una no pueda ahogar a la otra.
Limita sus reintentos
Se rinde y expone el fallo en vez de reintentar indefinidamente.
Avisa antes del techo
Alertas sobre el cupo restante, para que la primera señal no sea un 429 en producción.
Respuestas
Preguntas frecuentes
¿Cuáles son los límites reales?
Dependen de su plan y de la clase de endpoint, y se indican en su contrato y no aquí. Una cifra publicada quedaría obsoleta en una sola versión, y quien dimensionara con ella descubriría el límite real en producción. Lea las cabeceras: siempre están al día.
¿Cómo debe reaccionar un cliente ante un 429?
Respete `Retry-After` si está presente; si no, retroceda de forma exponencial con desfase aleatorio y limite el número de intentos. Reintentar de inmediato, o a intervalo fijo desde muchos trabajadores, convierte un límite breve en uno sostenido: la estampida que transforma un problema pequeño en una caída.
¿La resolución pública del pasaporte se limita igual?
No. La resolución es pública, cacheable y se espera que llegue a ráfagas, así que la gobiernan el cacheado y la capacidad en el borde, no su cuota. Que un producto se haga viral no debe consumir la cuota de la que depende su tubería de emisión, y por eso las dos vías se contabilizan aparte.
¿Cómo cargamos un catálogo histórico grande?
Por la vía de importación masiva y no iterando sobre el endpoint de recurso único. La vía masiva está diseñada para el rendimiento y se ejecuta de forma asíncrona con un trabajo que usted consulta; el endpoint por recurso está diseñado para la latencia. Usar el equivocado es la causa más común de limitación de tasa autoinfligida.
¿Los límites se aplican por clave o por organización?
Por organización, con visibilidad por clave. Eso importa cuando acota las claves por servicio: un servicio que se porta mal puede consumir el presupuesto compartido, y el desglose por clave es lo que le permite encontrarlo rápido en vez de por descarte.
Next step
Díganos sus volúmenes antes de construir
Tamaño del catálogo, ritmo de emisión y pico estacional. Preferimos dimensionar bien el plan a que descubra un techo en producción.