Belfort Docs

Límites de uso

Los límites se publican en cabeceras estándar, en todas las respuestas. Tu cliente no tiene que adivinar cuánto le queda ni cuánto esperar.

Las cabeceras

RateLimit-Limit: 100
RateLimit-Remaining: 87
RateLimit-Reset: 42
RateLimit: limit=100, remaining=87, reset=42

Reset son segundos hasta que puedas volver a pedir, no una marca de tiempo absoluta: así no depende de que el reloj de tu servidor esté sincronizado con el nuestro.

Y no es "cuándo caduca la petición más vieja" sino "cuándo el conteo baja del límite", que no es lo mismo cuando la ventana sigue registrando los intentos rechazados. Reportar lo primero diría "espera 3 segundos" cuando faltan cuarenta.

Si consumes la API desde un navegador, están expuestas vía CORS junto con Belfort-Request-Id. Emitir cabeceras que el navegador no puede leer es emitirlas para nadie.

Cuando te frenan

Recibes 429 con Retry-After. Pero no todos los 429 se arreglan esperando, y tratarlos igual bloquea un worker para nada:

RATE_LIMITED Vas demasiado rápido. Espera lo que diga Retry-After y reintenta.
PII_DECRYPT_CAP_REACHED Agotaste el presupuesto diario de revelado de datos personales. Se libera en ~24 horas: no es reintentable en ningún plazo razonable. Es un tope anti-exfiltración, puesto justo para que una key robada no pueda volcar el vault.
TRIAL_LIMIT_REACHED Se acabó el cupo del periodo de prueba. Esperar no lo arregla.

Recomendación concreta: topa el plazo que honras (30 segundos es razonable) y trata los dos últimos como no reintentables. Un Retry-After honesto de 86 400 segundos es correcto por nuestra parte y bloquearía tu worker un día entero si lo obedeces literalmente.

Cuáles son tus límites

Dependen de tu plan y del entorno, así que no se transcriben aquí: los publica la propia API en GET /v1/compliance/limits, que es la fuente única. Léelos en vez de copiarlos — cambian sin que cambie tu código.

Reintentos con cabeza

  • Espera exponencialmente y añade una variación aleatoria: sin ella, todos tus workers reintentan a la vez y reproducen el pico que causó el freno.
  • Usa Idempotency-Key en las escrituras. Reintentar sin ella es cómo se crean duplicados.
  • Los 503 también traen Retry-After. Respétalo.