Limites
Quantas requisições você pode fazer.
Requisições por minuto
Cada endpoint permite um número fixo de requisições por minuto. Para os endpoints de dados e para a leitura da conta, todas as chaves e tokens de uma conta contam juntos. Toda requisição conta, mesmo uma recusada.
| Endpoint | O quê | Limite por minuto |
|---|---|---|
| fetch-organization | Perfil da empresa | 60 |
| fetch-person | Perfil de pessoa | 60 |
| search-organizations | Busca & Exportação | 60 |
| fetch-document | Documentos | 5 |
| signals | Signals | 60 |
| account | Ler a conta | 30 |
| account, auth/tokens | Gerenciar bearer tokens; criar, alterar e excluir chaves, monitores e endpoints de webhook | 10 |
| account/webhook-endpoints | Verificar e testar um endpoint de webhook, rotacionar o secret | 6 |
Busca, documentos e Signals compartilham uma cota de 60 requisições por minuto. Documentos também têm um limite próprio, menor.
Requisições de escrita na conta, no Monitoramento e nos webhooks também contam para o limite da conta. Os mesmos números estão em “Custos e limites” em cada página de endpoint.
Os limites são os mesmos em toda assinatura de créditos. Se você precisa de mais requisições por minuto, um contrato Enterprise pode oferecer limites maiores.
Limite atingido
Acima do limite, a API responde com 429. O header Retry-After diz depois de quantos segundos você pode enviar requisições de novo. O mesmo número está no campo retry_after.
Toda resposta mostra nos headers quanta margem você ainda tem:
| Header | Significado | Exemplo |
|---|---|---|
| X-RateLimit-Limit | O limite por minuto deste endpoint. |
30 |
| X-RateLimit-Remaining | Quantas requisições ainda são possíveis neste minuto. |
0 |
| Retry-After |
Só com 429: segundos até a próxima requisição possível.
|
17 |
| X-RateLimit-Reset |
Só com 429: o momento em que você pode continuar, como tempo Unix.
|
1793519682 |
1{2 "error": "Too many requests",3 "message": "Rate limit exceeded. Retry after 17 seconds.",4 "retry_after": 175}
Quando você envia muitas requisições, observe X-RateLimit-Remaining e desacelere por conta própria antes que a API responda com 429. Uma requisição acima do limite não custa nada.
Timeouts
A maioria das respostas chega em poucos segundos. Modo IA, o recurso news, consultas em tempo real, fetch-person e documentos demoram mais, porque buscamos documentos e dados em tempo real diretamente no registro.
Configure o timeout do seu cliente para pelo menos 120 segundos, especialmente para Tempo real, fetch-person e documentos. Um timeout curto demais interrompe requisições que estão quase terminando.
Para documentos, existe também async=true: a API responde na hora com 202 e busca o documento em segundo plano, veja fetch-document.
408, para documentos 504 com Retry-After. Nada é cobrado. Repita a requisição um pouco mais tarde. Se só a consulta ao vivo do Tempo real falhar, você recebe o perfil da empresa com os dados armazenados, sem o acréscimo de Tempo real.
Repetir sem cobrança dupla
Se o seu cliente interrompe uma requisição, ela ainda pode terminar do nosso lado e ser cobrada. Com o header Idempotency-Key, a repetição então não custa nada.
Escolha uma chave separada para cada requisição e envie-a sem alteração na repetição. Uma chave tem de 1 a 128 caracteres: letras, dígitos, ponto, sublinhado, dois-pontos e hífen, começando com letra ou dígito.
curl -G "https://handelsregister.ai/api/v1/fetch-organization" \ -H "x-api-key: SUA_CHAVE_DE_API" \ -H "Idempotency-Key: hetzner-perfil-2026-11-01" \ --data-urlencode "q=Ansbach HRB 6089"
| Caso | Endpoints de dados | Monitoramento e webhooks |
|---|---|---|
| Chave obrigatória | não, opcional |
sim, senão 428
|
| Janela | 24 horas | 24 horas |
| Mesma chave, mesmos parâmetros | Resultado de novo, sem cobrança | Resposta armazenada com seu status |
| Mesma chave, parâmetros diferentes |
422 idempotency_key_reused |
409 idempotency_conflict |
| Depois de um erro | A chave continua livre | O mesmo erro volta, é preciso uma chave nova |
Endpoints de dados
fetch-organization, fetch-person, search-organizations e fetch-document aceitam a chave como opção. Se você repetir uma requisição com a mesma chave e os mesmos parâmetros em até 24 horas, recebe o resultado de novo, sem cobrança.
A primeira resposta traz o header Idempotency-Status: created, cada repetição Idempotency-Status: replayed e meta.request_credit_cost: 0. Uma repetição não precisa de saldo.
Só um resultado entregue vincula a chave. Assim, depois de um erro, você pode continuar usando a mesma chave. A mesma chave com parâmetros diferentes gera 422 com idempotency_key_reused. Os endpoints de dados ignoram uma chave em outro formato, então siga o formato exatamente.
signals não aceita idempotency key.
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}
Monitoramento e webhooks
Requisições de escrita em /v1/account/monitors, /v1/account/webhook-endpoints e /v1/account/webhook-deliveries precisam da chave. Sem ela, a API responde com 428; uma chave no formato errado gera 400.
Em até 24 horas, a mesma chave com os mesmos parâmetros retorna a resposta armazenada com seu status, mais Idempotency-Status: replayed. Isso vale também para erros. Para uma nova tentativa, como verificar de novo, você usa portanto uma chave nova.
A mesma chave com parâmetros diferentes gera 409 com idempotency_conflict. Se a primeira requisição ainda estiver rodando, você recebe 409 com idempotency_in_progress.
Planeje suas repetições
Nem todo erro merece uma segunda tentativa. Veja como proceder:
- Repetir:
408,429depois deRetry-Aftere5xx. Espere mais entre as tentativas a cada vez, por exemplo 2, 4 e 8 segundos, e pare após algumas tentativas. - Corrigir primeiro, depois reenviar:
400,401,402,403,404e422. Enviar a mesma requisição de novo traz o mesmo resultado. - Envie uma idempotency key com requisições pagas. Assim, uma repetição após uma interrupção não custa nada.