Is your script or automation tool (n8n, Make, in-house script…) getting a 429 error with the message "Rate limit exceeded"? The number of calls sent to the Fincome API is above the allowed limit. Here are the current limits, the right way to handle a 429 error and the method to follow to load a large volume of data.

1. Key takeaways in 30 seconds

• The Fincome API accepts 5 requests per second and 200 requests per minute, per Fincome account.
• Both limits apply at the same time, on all /v1 endpoints. Over a full minute, that is about 3 requests per second on average.
• All API keys of an account share this budget: creating several keys or running batches in parallel won't make you go faster.
• On a 429 error, wait for the delay given in the Retry-After header, then send the request again.
• For a large historical import, contact support before you start loading.

2. The limits in detail

Counters reset at the start of each second and each minute (UTC time).

Rejected requests count too. If your script retries in a tight loop after a 429 error, it uses up the rest of the minute's 200 requests and stays blocked until the next minute starts.

API responses don't show the remaining quota: your script has to pace itself instead of waiting for a 429 error.

3. What should I do when I get a 429 error?

The API answers 429 Too Many Requests with the body { "detail": "Rate limit exceeded." }. The request was not processed: you need to send it again.

1. Read the Retry-After header of the response. It is 1 if you went over the per-second limit, or the number of seconds left in the current minute if you went over the per-minute limit.
2. Wait for that delay, then send the same request again.
3. If 429 errors keep coming, increase the delay at each new attempt (exponential backoff).
4. Log the failed requests (endpoint, object ID, timestamp) so you can check afterwards that no object was left out.

Dashboard refresh: a call to /v1/utils/refresh less than 30 seconds after the previous one gets a 429 error with a plain-text message and no Retry-After header. Call it once, at the end of your import, not after each object you send.

4. Loading a large volume of data

The API is designed for ongoing updates: new invoices, subscription changes, enriching your dimensions. For a historical import or an initial load of several thousand objects:

1. Let support know before you start, through the chat. A higher limit can be considered for a one-off import.
2. Consider the Excel file import. You can load your whole history at once, from the interface (see Prepare my file and Import my file) or through the API with the Import an Excel dataset endpoints.
3. If you send objects one by one, keep a steady pace of 3 requests per second at most, in dependency order: customers, then products and prices, then subscriptions, then invoices and invoice line items.
4. To read your data, use limit=1000 on list endpoints: you make fewer calls.
5. Finish with a single call to /v1/utils/refresh to update your dashboards.

5. Rate limit or sync delay?

The limits described here only apply to the Fincome public API, the one you call yourself. They don't apply to:

• native connectors (Stripe, Chargebee, Pennylane, Sellsy, HubSpot, Salesforce…), which sync automatically. A first sync on a large history can take several days, depending on the source tool's own limits;
• Excel file imports from the interface;
• the Fincome MCP used from Claude or ChatGPT.

6. FAQ

→ Where can I find these limits in the technical documentation?
In the Rate limiting section of the API documentation.

→ Can the limit of my account be increased?
For a one-off need, such as a large historical import, contact support before you start your import and tell us the volume you need to load.

→ I send my requests in several parallel batches, why do I still get 429 errors?
Because all calls of an account share the same limit, whatever the API key or endpoint used. Two batches at 3 requests per second make 6 requests per second, above the limit. A single steady flow works better.

→ My API import finished but some invoices are missing.
Requests rejected with a 429 error were not processed. Send them again from your logs, then check the result in Data > Invoices or Data > Invoice line items.

→ How long after my calls are the dashboards up to date?
Data sent through the API is taken into account at the next dashboard refresh. Trigger it with /v1/utils/refresh once your import is finished.

→ My error persists despite pacing my calls. What should I send to support?
Message us through the chat with the endpoint called, the body of the error response and the timestamp of the request. Never send your API key.

Related articles

• Load your billing data via API
• Enrich your billing data via API
• Prepare my file
• Import my file

Updated on: 25/09/2026