> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.fincome.co/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Fincome API rate limits (429 error)

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

| Limit | Value | Scope |
| ---- | ---- | ---- |
| Requests per second | 5 | Per Fincome account, across all /v1 endpoints and all API keys |
| Requests per minute | 200 | Per Fincome account, across all /v1 endpoints and all API keys |
| Dashboard refresh (`POST /v1/utils/refresh`) | 1 call every 30 seconds | Per Fincome account |

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.

| Watch out: a script that ignores 429 errors leaves gaps in your data (missing invoices or credit notes, subscriptions not created). If your MRR looks incomplete after an API import, check the rejected requests first.

**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](https://help.fincome.co/en/article/prepare-my-file-65s5k8/) and [Import my file](https://help.fincome.co/en/article/import-my-file-p8jf4p/)) 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](https://docs.fincome.co/api#section/Introduction/Rate-limiting).

**→ 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](https://help.fincome.co/en/article/load-your-billing-data-via-api-1ek1snn/)
* [Enrich your billing data via API](https://help.fincome.co/en/article/enrich-your-billing-data-via-api-1hvruwt/)
* [Prepare my file](https://help.fincome.co/en/article/prepare-my-file-65s5k8/)
* [Import my file](https://help.fincome.co/en/article/import-my-file-p8jf4p/)