Límites de uso
Toda respuesta —incluidos los errores— dice cuánto cupo le queda a la llave. No hace falta pedirlo aparte: viene en cabeceras estándar de límite de tasa en cada petición.
RateLimit-Limit: 57
RateLimit-Remaining: 56
RateLimit-Reset: 3600
RateLimit-Policy: hour;q=60;w=3600, day;q=300;w=86400| Cabecera | Qué dice |
|---|---|
RateLimit-Limit | El techo de la ventana más cercana a morder. |
RateLimit-Remaining | Lo que queda de esa ventana, con esta petición ya descontada. |
RateLimit-Reset | Segundos hasta que esa ventana se libera del todo — la longitud entera de la ventana deslizante, redondeada hacia arriba a propósito: nunca dice «vuelva» antes de tiempo. |
RateLimit-Policy | Las dos ventanas completas, por hora y por día. |
Retry-After | Segundos que conviene esperar. Solo aparece en los errores donde esperar arregla algo: 429, el 409 en vuelo y el 503. |
Por qué anuncia la ventana más cerca de morder
Con 5 llamadas libres en la hora y 1 en el día, lo que se anuncia es 1 — decir 5 sería invitar a un 429 en la segunda petición. Si su sistema solo mira RateLimit-Remaining sin fijarse en RateLimit-Policy, ya está mirando la ventana correcta.
Tres ventanas, no una
- Por hora y por día, para las rutas que consultan y emiten. Compartidas entre todas ellas.
- Una propia para
/v1/status, generosa de fábrica (240/hora). Preguntar por el estado de la llave no gasta el cupo de emitir — antes sí lo hacía, y un monitor que preguntaba cada minuto se comía la hora entera. Sigue contándose aparte: una ruta sin medir sería un martillo gratis para una llave robada. - Un techo de monto por documento (
amount_limit,429), independiente de las dos anteriores: cuánto puede valer un solo DTE con esa llave.
Se cuentan antes de trabajar
Los techos se descuentan antes de reservar el correlativo, no después de terminar la petición. Una petición que muere a medio camino igual gastó su cupo. Es conservador a propósito: con trabajo irreversible al otro lado de la puerta —un correlativo, una firma—, el que pierde un turno de cupo es el integrador honesto, nunca el que intenta forzar la llave.
El de monto (amount_limit) también se comprueba antes de reservar, así que no gasta correlativo: un documento demasiado grande para esta llave nunca llega a ocupar un número.
Qué hacer con un 429
{
"error": {
"code": "rate_limited",
"message": "Se alcanzó el techo por hora de esta llave",
"details": { "window": "hour", "remaining": 0, "retryAfterSeconds": 1180 }
}
}details.window dice cuál de las tres ventanas fue, y details.retryAfterSeconds —igual que la cabecera Retry-After— cuánto conviene esperar. Reintentar antes de ese plazo solo va a repetir el mismo 429.
Otras guías
Emitir un DTE
Cómo llamar a POST /v1/dte, qué llega firmado por dentro y las tres respuestas que puede recibir.
Leer →Preparar y firmar por separado
Por qué separar la reserva del correlativo de la firma, el prepareToken y sus 15 minutos, y qué pasa si el documento cambia entre las dos llamadas.
Leer →