Votre script ou votre outil d'automatisation (n8n, Make, script maison…) reçoit une erreur 429 avec le message « Rate limit exceeded » ? Le nombre d'appels envoyés à l'API Fincome dépasse la limite autorisée. Voici les limites en vigueur, la bonne façon de gérer une erreur 429 et la méthode à suivre pour charger un gros volume de données.

1. À retenir en 30 secondes

• L'API Fincome accepte 5 requêtes par seconde et 200 requêtes par minute, par compte Fincome.
• Ces deux plafonds s'appliquent en même temps, sur tous les endpoints /v1. Sur une minute complète, cela revient à environ 3 requêtes par seconde en moyenne.
• Toutes les clés API d'un même compte partagent ce budget : créer plusieurs clés ou lancer des batchs en parallèle ne permet pas d'aller plus vite.
• En cas d'erreur 429, attendez le délai indiqué dans l'en-tête Retry-After, puis renvoyez la requête.
• Pour une reprise d'historique importante, contactez le support avant de lancer le chargement.

2. Les limites en détail

Les compteurs repartent de zéro au début de chaque seconde et de chaque minute (heure UTC).

Les requêtes refusées sont elles aussi comptabilisées. Si votre script relance en boucle après une erreur 429, il consomme le reste des 200 requêtes de la minute et reste bloqué jusqu'à la minute suivante.

Les réponses de l'API n'indiquent pas le quota restant : c'est à votre script de régler son rythme, sans attendre de recevoir une erreur 429.

3. Que faire quand je reçois une erreur 429 ?

L'API répond 429 Too Many Requests avec le corps { "detail": "Rate limit exceeded." }. La requête n'a pas été traitée : il faut la renvoyer.

1. Lisez l'en-tête Retry-After de la réponse. Il vaut 1 si vous avez dépassé la limite par seconde, ou le nombre de secondes restantes dans la minute en cours si vous avez dépassé la limite par minute.
2. Attendez ce délai, puis renvoyez la même requête.
3. Si les erreurs 429 continuent, allongez le délai à chaque nouvel essai (recul exponentiel).
4. Journalisez les requêtes en erreur (endpoint, identifiant de l'objet, horodatage) pour vérifier ensuite qu'aucun objet n'a été oublié.

Cas du rafraîchissement du dashboard : un appel à /v1/utils/refresh moins de 30 secondes après le précédent reçoit une erreur 429 avec un message texte, sans en-tête Retry-After. Appelez-le une seule fois, à la fin de votre import, et non après chaque objet envoyé.

4. Charger un gros volume de données

L'API est pensée pour les mises à jour au fil de l'eau : nouvelles factures, changements d'abonnement, enrichissement de vos axes. Pour une reprise d'historique ou un chargement initial de plusieurs milliers d'objets :

1. Prévenez le support avant de commencer, via le chat. Une limite plus élevée peut être étudiée pour un import ponctuel.
2. Envisagez l'import de fichier Excel. Vous pouvez charger tout votre historique en une fois, depuis l'interface (voir Préparer mon fichier et Importer mon fichier) ou par l'API avec les endpoints Import an Excel dataset.
3. Si vous envoyez objet par objet, gardez un rythme régulier de 3 requêtes par seconde maximum, dans l'ordre des dépendances : clients, puis produits et prix, puis abonnements, puis factures et lignes de facture.
4. Pour lire vos données, utilisez limit=1000 sur les endpoints de liste : vous faites moins d'appels.
5. Terminez par un seul appel à /v1/utils/refresh pour mettre à jour vos dashboards.

5. Rate limit ou délai de synchronisation ?

Les limites décrites ici concernent uniquement l'API publique Fincome, celle que vous appelez vous-même. Elles ne s'appliquent pas :

• aux connecteurs natifs (Stripe, Chargebee, Pennylane, Sellsy, HubSpot, Salesforce…), qui se synchronisent automatiquement. Une première synchronisation sur un historique important peut prendre plusieurs jours, selon les limites de l'outil source ;
• à l'import de fichier Excel depuis l'interface ;
• au MCP Fincome utilisé depuis Claude ou ChatGPT.

6. FAQ

→ Où trouver ces limites dans la documentation technique ?
Dans la section Rate limiting de la documentation de l'API.

→ Peut-on augmenter la limite de mon compte ?
Pour un besoin ponctuel, comme une grosse reprise d'historique, contactez le support avant de lancer votre import en précisant le volume à charger.

→ J'envoie mes requêtes en plusieurs batchs parallèles, pourquoi ai-je encore des 429 ?
Parce que tous les appels d'un compte partagent la même limite, quelles que soient la clé API ou l'endpoint utilisés. Deux batchs à 3 requêtes par seconde font 6 requêtes par seconde, au-dessus du plafond. Mieux vaut un seul flux régulier.

→ Mon import par API s'est terminé mais il manque des factures.
Les requêtes refusées en 429 n'ont pas été traitées. Relancez-les à partir de vos logs, puis vérifiez le résultat dans Données > Factures ou Données > Lignes de facture.

→ Combien de temps après mes appels les dashboards sont-ils à jour ?
Les données envoyées par API sont prises en compte au prochain rafraîchissement du dashboard. Déclenchez-le avec /v1/utils/refresh une fois votre import terminé.

→ Mon erreur persiste malgré la temporisation. Que dois-je transmettre au support ?
Écrivez-nous via le chat en précisant l'endpoint appelé, le corps de la réponse d'erreur et l'horodatage de la requête. Ne transmettez jamais votre clé API.

Articles liés

• Charger ses données de facturation via API
• Enrichir ses données de facturation via API
• Préparer mon fichier
• Importer mon fichier

Mis à jour le : 25/09/2026