Limites
Combien de requêtes tu peux envoyer.
Requêtes par minute
Chaque endpoint autorise un nombre fixe de requêtes par minute. Pour les endpoints de données et la lecture du compte, toutes les clés et tous les tokens d’un compte comptent ensemble. Chaque requête compte, même refusée.
| Endpoint | Quoi | Limite par minute |
|---|---|---|
| fetch-organization | Profil d’entreprise | 60 |
| fetch-person | Profil de personne | 60 |
| search-organizations | Recherche & Export | 60 |
| fetch-document | Documents | 5 |
| signals | Signals | 60 |
| account | Lire le compte | 30 |
| account, auth/tokens | Gérer les bearer tokens ; créer, modifier et supprimer des clés, moniteurs et endpoints webhook | 10 |
| account/webhook-endpoints | Vérifier et tester un endpoint webhook, faire tourner le secret | 6 |
Recherche, documents et Signals partagent un quota de 60 requêtes par minute. Les documents ont en plus leur propre limite, plus basse.
Les requêtes d’écriture sur le compte, le Monitoring et les webhooks comptent aussi dans la limite du compte. Les mêmes chiffres figurent sous « Coûts et limites » sur chaque page d’endpoint.
Les limites sont les mêmes dans chaque abonnement de crédits. S’il te faut plus de requêtes par minute, un contrat Enterprise peut t’offrir des limites plus élevées.
Limite atteinte
Au-delà de la limite, l’API répond 429. Le header Retry-After indique au bout de combien de secondes tu peux de nouveau envoyer des requêtes. Le même nombre figure dans le champ retry_after.
Chaque réponse indique dans ses headers la marge qu’il te reste :
| Header | Signification | Exemple |
|---|---|---|
| X-RateLimit-Limit | La limite par minute de cet endpoint. |
30 |
| X-RateLimit-Remaining | Combien de requêtes sont encore possibles dans cette minute. |
0 |
| Retry-After |
Uniquement avec 429 : secondes jusqu’à la prochaine requête possible.
|
17 |
| X-RateLimit-Reset |
Uniquement avec 429 : le moment où tu peux continuer, en temps Unix.
|
1793519682 |
1{2 "error": "Too many requests",3 "message": "Rate limit exceeded. Retry after 17 seconds.",4 "retry_after": 175}
Quand tu envoies beaucoup de requêtes, surveille X-RateLimit-Remaining et ralentis toi-même avant que l’API ne réponde 429. Une requête au-delà de la limite ne coûte rien.
Délais d’attente
La plupart des réponses arrivent en quelques secondes. Le mode IA, la fonctionnalité news, les récupérations en temps réel, fetch-person et les documents prennent plus de temps, car nous récupérons les documents et les données en temps réel directement au registre.
Règle le délai d’attente de ton client sur au moins 120 secondes, en particulier pour le mode temps réel, fetch-person et les documents. Un délai trop court interrompt des requêtes sur le point d’aboutir.
Pour les documents, il existe aussi async=true : l’API répond immédiatement avec 202 et récupère le document en arrière-plan, voir fetch-document.
408, pour les documents 504 avec Retry-After. Rien n’est facturé. Réessaie la requête un peu plus tard. Si seule la récupération en direct du mode temps réel échoue, tu obtiens le profil d’entreprise avec les données enregistrées, sans le supplément temps réel.
Réessayer sans double facturation
Si ton client interrompt une requête, elle peut quand même aboutir de notre côté et être facturée. Avec le header Idempotency-Key, la nouvelle tentative ne coûte alors rien.
Choisis une clé distincte pour chaque requête et renvoie-la inchangée lors de la nouvelle tentative. Une clé compte 1 à 128 caractères : lettres, chiffres, point, tiret bas, deux-points et trait d’union, en commençant par une lettre ou un chiffre.
curl -G "https://handelsregister.ai/api/v1/fetch-organization" \ -H "x-api-key: TA_CLE_API" \ -H "Idempotency-Key: hetzner-profil-2026-11-01" \ --data-urlencode "q=Ansbach HRB 6089"
| Cas | Endpoints de données | Monitoring et webhooks |
|---|---|---|
| Clé obligatoire | non, facultative |
oui, sinon 428
|
| Fenêtre | 24 heures | 24 heures |
| Même clé, mêmes paramètres | Résultat à nouveau, sans facturation | Réponse enregistrée avec son statut |
| Même clé, paramètres différents |
422 idempotency_key_reused |
409 idempotency_conflict |
| Après une erreur | La clé reste libre | La même erreur revient, nouvelle clé nécessaire |
Endpoints de données
fetch-organization, fetch-person, search-organizations et fetch-document acceptent la clé en option. Si tu répètes une requête avec la même clé et les mêmes paramètres dans les 24 heures, tu obtiens de nouveau le résultat, sans facturation.
La première réponse porte le header Idempotency-Status: created, chaque répétition Idempotency-Status: replayed et meta.request_credit_cost: 0. Une répétition ne nécessite pas de solde.
Seul un résultat livré lie la clé. Après une erreur, tu peux donc continuer à utiliser la même clé. La même clé avec des paramètres différents donne 422 avec idempotency_key_reused. Les endpoints de données ignorent une clé dans un autre format, respecte donc exactement le format.
signals n’accepte pas de clé d’idempotence.
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 et webhooks
Les requêtes d’écriture vers /v1/account/monitors, /v1/account/webhook-endpoints et /v1/account/webhook-deliveries nécessitent la clé. Sans elle, l’API répond 428 ; une clé au mauvais format donne 400.
Dans les 24 heures, la même clé avec les mêmes paramètres renvoie la réponse enregistrée avec son statut, plus Idempotency-Status: replayed. Cela vaut aussi pour les erreurs. Pour une nouvelle tentative, comme une nouvelle vérification, tu utilises donc une nouvelle clé.
La même clé avec des paramètres différents donne 409 avec idempotency_conflict. Si la première requête est encore en cours, tu reçois 409 avec idempotency_in_progress.
Planifier les nouvelles tentatives
Toutes les erreurs ne valent pas une seconde tentative. Voici comment procéder :
- Réessayer :
408,429aprèsRetry-Afteret5xx. Attends chaque fois plus longtemps entre les tentatives, par exemple 2, 4 et 8 secondes, et arrête après quelques tentatives. - Corriger d’abord, puis renvoyer :
400,401,402,403,404et422. Renvoyer la même requête donne le même résultat. - Envoie une clé d’idempotence avec les requêtes payantes. Une nouvelle tentative après une interruption ne coûte alors rien.