Limiti
Quante richieste puoi fare.
Richieste al minuto
Ogni endpoint consente un numero fisso di richieste al minuto. Per gli endpoint dati e per la lettura dell’account contano insieme tutte le chiavi e i token di un account. Ogni richiesta conta, anche una rifiutata.
| Endpoint | Cosa | Limite al minuto |
|---|---|---|
| fetch-organization | Profilo aziendale | 60 |
| fetch-person | Profilo persona | 60 |
| search-organizations | Ricerca & Export | 60 |
| fetch-document | Documenti | 5 |
| signals | Signals | 60 |
| account | Leggere l’account | 30 |
| account, auth/tokens | Gestire bearer token; creare, modificare ed eliminare chiavi, monitor ed endpoint webhook | 10 |
| account/webhook-endpoints | Verificare e testare un endpoint webhook, ruotare il secret | 6 |
Ricerca, documenti e Signals condividono una quota di 60 richieste al minuto. I documenti hanno inoltre un loro limite più basso.
Anche le richieste di scrittura su account, Monitoring e webhook contano per il limite dell’account. Gli stessi numeri sono indicati in “Costi e limiti” su ogni pagina endpoint.
I limiti sono gli stessi in ogni abbonamento a crediti. Se ti servono più richieste al minuto, un contratto Enterprise può darti limiti più alti.
Limite raggiunto
Oltre il limite l’API risponde con 429. L’header Retry-After ti dice dopo quanti secondi puoi inviare di nuovo richieste. Lo stesso numero è nel campo retry_after.
Ogni risposta mostra negli header quanto margine ti resta:
| Header | Significato | Esempio |
|---|---|---|
| X-RateLimit-Limit | Il limite al minuto di questo endpoint. |
30 |
| X-RateLimit-Remaining | Quante altre richieste sono possibili in questo minuto. |
0 |
| Retry-After |
Solo con 429: secondi fino alla prossima richiesta possibile.
|
17 |
| X-RateLimit-Reset |
Solo con 429: il momento in cui puoi continuare, come tempo Unix.
|
1793519682 |
1{2 "error": "Too many requests",3 "message": "Rate limit exceeded. Retry after 17 seconds.",4 "retry_after": 175}
Quando invii molte richieste, osserva X-RateLimit-Remaining e rallenta tu stesso prima che l’API risponda con 429. Una richiesta oltre il limite non costa nulla.
Timeout
La maggior parte delle risposte arriva in pochi secondi. Modalità AI, la feature news, i recuperi in tempo reale, fetch-person e i documenti durano di più, perché documenti e dati in tempo reale li recuperiamo direttamente dal registro.
Imposta il timeout del tuo client ad almeno 120 secondi, soprattutto per Tempo reale, fetch-person e documenti. Un timeout troppo breve interrompe richieste che stanno per concludersi.
Per i documenti c’è anche async=true: l’API risponde subito con 202 e recupera il documento in background, vedi fetch-document.
408, per i documenti 504 con Retry-After. Non viene addebitato nulla. Riprova la richiesta poco dopo. Se fallisce solo il recupero in diretta per Tempo reale, ricevi il profilo aziendale con i dati salvati, senza il supplemento Tempo reale.
Riprovare senza doppio addebito
Se il tuo client interrompe una richiesta, questa può comunque concludersi da noi ed essere addebitata. Con l’header Idempotency-Key il nuovo tentativo non costa nulla.
Scegli una chiave separata per ogni richiesta e inviala invariata con il nuovo tentativo. Una chiave ha da 1 a 128 caratteri: lettere, cifre, punto, trattino basso, due punti e trattino, iniziando con una lettera o una cifra.
curl -G "https://handelsregister.ai/api/v1/fetch-organization" \ -H "x-api-key: LA_TUA_CHIAVE_API" \ -H "Idempotency-Key: hetzner-profilo-2026-11-01" \ --data-urlencode "q=Ansbach HRB 6089"
| Caso | Endpoint dati | Monitoring e webhook |
|---|---|---|
| Chiave obbligatoria | no, facoltativa |
sì, altrimenti 428
|
| Finestra | 24 ore | 24 ore |
| Stessa chiave, stessi parametri | Di nuovo il risultato, senza addebito | Risposta salvata con il suo stato |
| Stessa chiave, parametri diversi |
422 idempotency_key_reused |
409 idempotency_conflict |
| Dopo un errore | La chiave resta libera | Torna lo stesso errore, serve una nuova chiave |
Endpoint dati
fetch-organization, fetch-person, search-organizations e fetch-document accettano la chiave come opzione. Se ripeti una richiesta con la stessa chiave e gli stessi parametri entro 24 ore, ricevi di nuovo il risultato, senza addebito.
La prima risposta porta l’header Idempotency-Status: created, ogni nuovo tentativo Idempotency-Status: replayed e meta.request_credit_cost: 0. Un nuovo tentativo non richiede saldo.
Solo un risultato consegnato vincola la chiave. Dopo un errore puoi quindi continuare a usare la stessa chiave. La stessa chiave con parametri diversi dà 422 con idempotency_key_reused. Gli endpoint dati ignorano una chiave in un formato diverso, quindi rispetta esattamente il formato.
signals non accetta un 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}
Monitoring e webhook
Le richieste di scrittura a /v1/account/monitors, /v1/account/webhook-endpoints e /v1/account/webhook-deliveries richiedono la chiave. Senza, l’API risponde con 428; una chiave nel formato sbagliato dà 400.
Entro 24 ore, la stessa chiave con gli stessi parametri restituisce la risposta salvata con il suo stato, più Idempotency-Status: replayed. Vale anche per gli errori. Per un nuovo tentativo, come una nuova verifica, usi quindi una nuova chiave.
La stessa chiave con parametri diversi dà 409 con idempotency_conflict. Se la prima richiesta è ancora in corso, ricevi 409 con idempotency_in_progress.
Pianificare i nuovi tentativi
Non ogni errore merita un secondo tentativo. Ecco come procedere:
- Riprova:
408,429dopoRetry-Aftere5xx. Aspetta ogni volta più a lungo tra i tentativi, ad esempio 2, 4 e 8 secondi, e fermati dopo qualche tentativo. - Prima correggi, poi reinvia:
400,401,402,403,404e422. Reinviare la stessa richiesta porta allo stesso risultato. - Invia un idempotency key con le richieste a pagamento. Così un nuovo tentativo dopo un’interruzione non costa nulla.