Límites
Cuántas solicitudes puedes hacer.
Solicitudes por minuto
Cada endpoint permite un número fijo de solicitudes por minuto. Para los endpoints de datos y la lectura de la cuenta, cuentan juntas todas las claves y tokens de una cuenta. Cada solicitud cuenta, incluso una rechazada.
| Endpoint | Qué | Límite por minuto |
|---|---|---|
| fetch-organization | Perfil de empresa | 60 |
| fetch-person | Perfil de persona | 60 |
| search-organizations | Búsqueda y exportación | 60 |
| fetch-document | Documentos | 5 |
| signals | Signals | 60 |
| account | Leer la cuenta | 30 |
| account, auth/tokens | Gestionar bearer tokens; crear, modificar y eliminar claves, monitores y endpoints de webhook | 10 |
| account/webhook-endpoints | Verificar y probar un endpoint de webhook, rotar el secreto | 6 |
Búsqueda, documentos y Signals comparten una cuota de 60 solicitudes por minuto. Los documentos tienen además su propio límite, más bajo.
Las solicitudes de escritura a la cuenta, Monitoring y webhooks cuentan también para el límite de la cuenta. Las mismas cifras figuran en “Costes y límites” en cada página de endpoint.
Los límites son los mismos en todas las suscripciones de créditos. Si necesitas más solicitudes por minuto, un contrato Enterprise puede darte límites más altos.
Límite alcanzado
Por encima del límite, la API responde con 429. El header Retry-After te dice tras cuántos segundos puedes volver a enviar solicitudes. El mismo número está en el campo retry_after.
Cada respuesta muestra en headers cuánto margen te queda:
| Header | Significado | Ejemplo |
|---|---|---|
| X-RateLimit-Limit | El límite por minuto de este endpoint. |
30 |
| X-RateLimit-Remaining | Cuántas solicitudes más son posibles en este minuto. |
0 |
| Retry-After |
Solo con 429: segundos hasta la siguiente solicitud posible.
|
17 |
| X-RateLimit-Reset |
Solo con 429: el momento en que puedes continuar, como tiempo Unix.
|
1793519682 |
1{2 "error": "Too many requests",3 "message": "Rate limit exceeded. Retry after 17 seconds.",4 "retry_after": 175}
Cuando envíes muchas solicitudes, vigila X-RateLimit-Remaining y frena tú antes de que la API responda con 429. Una solicitud por encima del límite no cuesta nada.
Timeouts
La mayoría de las respuestas llegan en pocos segundos. El modo IA, la función news, las consultas en tiempo real, fetch-person y los documentos tardan más, porque obtenemos documentos y datos en tiempo real directamente del registro.
Configura el timeout de tu cliente en al menos 120 segundos, sobre todo para Tiempo real, fetch-person y documentos. Un timeout demasiado corto interrumpe solicitudes que están a punto de terminar.
Para documentos existe además async=true: la API responde enseguida con 202 y obtiene el documento en segundo plano, consulta fetch-document.
408, en documentos 504 con Retry-After. No se cobra nada. Repite la solicitud un poco más tarde. Si solo falla la consulta en directo de Tiempo real, recibes el perfil de empresa con los datos guardados, sin el recargo de Tiempo real.
Reintentar sin cobro doble
Si tu cliente interrumpe una solicitud, esta puede terminar igualmente en nuestro lado y cobrarse. Con el header Idempotency-Key, el reintento no cuesta nada.
Elige una clave distinta para cada solicitud y envíala sin cambios en el reintento. Una clave tiene de 1 a 128 caracteres: letras, dígitos, punto, guion bajo, dos puntos y guion, empezando por una letra o un dígito.
curl -G "https://handelsregister.ai/api/v1/fetch-organization" \ -H "x-api-key: TU_CLAVE_API" \ -H "Idempotency-Key: hetzner-perfil-2026-11-01" \ --data-urlencode "q=Ansbach HRB 6089"
| Caso | Endpoints de datos | Monitoring y webhooks |
|---|---|---|
| Clave obligatoria | no, opcional |
sí, si no 428
|
| Ventana | 24 horas | 24 horas |
| Misma clave, mismos parámetros | Resultado de nuevo, sin cobro | Respuesta guardada con su estado |
| Misma clave, parámetros distintos |
422 idempotency_key_reused |
409 idempotency_conflict |
| Tras un error | La clave queda libre | Vuelve el mismo error, hace falta una clave nueva |
Endpoints de datos
fetch-organization, fetch-person, search-organizations y fetch-document aceptan la clave como opción. Si repites una solicitud con la misma clave y los mismos parámetros en 24 horas, recibes de nuevo el resultado, sin cobro.
La primera respuesta lleva el header Idempotency-Status: created, cada reintento Idempotency-Status: replayed y meta.request_credit_cost: 0. Un reintento no necesita saldo.
Solo un resultado entregado vincula la clave. Así que tras un error puedes seguir usando la misma clave. La misma clave con parámetros distintos da 422 con idempotency_key_reused. Los endpoints de datos ignoran una clave con otro formato, así que respeta exactamente el formato.
signals no acepta clave de idempotencia.
1{2 "error": "idempotency_key_reused",3 "message": "This Idempotency-Key was already used with different parameters.",4 "meta": {5 "request_credit_cost": 0,6 "credits_remaining": 1457 }8}
Monitoring y webhooks
Las solicitudes de escritura a /v1/account/monitors, /v1/account/webhook-endpoints y /v1/account/webhook-deliveries necesitan la clave. Sin ella, la API responde con 428; una clave con formato incorrecto da 400.
En 24 horas, la misma clave con los mismos parámetros devuelve la respuesta guardada con su estado, más Idempotency-Status: replayed. Esto también aplica a los errores. Para un nuevo intento, como volver a verificar, usas por tanto una clave nueva.
La misma clave con parámetros distintos da 409 con idempotency_conflict. Si la primera solicitud sigue en curso, recibes 409 con idempotency_in_progress.
Planificar los reintentos
No todo error merece un segundo intento. Así debes proceder:
- Reintentar:
408,429trasRetry-Aftery5xx. Espera cada vez más entre intentos, por ejemplo 2, 4 y 8 segundos, y para tras unos pocos intentos. - Corregir primero y luego reenviar:
400,401,402,403,404y422. Enviar la misma solicitud otra vez da el mismo resultado. - Envía una clave de idempotencia con las solicitudes de pago. Así un reintento tras una interrupción no cuesta nada.