> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qonto.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Usage & Best Practices

<Accordion title="Rate limits: What are they and how to handle them?">
  ### **What are rate limits?**

  API rate limits are restrictions set on how many times an API can be called within a specific period of time. They are commonly used to:

  * **Protect the API from overuse or abuse** (such as from malicious actors or poorly written code)
  * **Ensure fair usage** among all users
  * **Maintain performance and stability** of the service

  ***

  ### **How to handle them at Qonto?**

  The frequency of your requests should respect the following rate limitations:

  * **1 000 requests / 10 seconds**
  * **10 000 requests / 10 minutes**

  If you don’t respect those rate limitations, you will get a `429 Too Many Requests` error.

  Additionally, we will throttle if there are more than **200 requests with status 401** within **1 hour**.

  Rate limitations are applied per IP address.
</Accordion>

<Accordion title="How to test integrations in Sandbox?">
  * You need to set up your Sandbox environment
  * Play with dummy data by making API calls using your Sandbox base URLs
  * Check if the API responses are the expected ones

  [Here](https://docs.qonto.com/get-started/general/developer-guidelines#log-in-to-the-sandbox-web-app) is a thorough explanation on how to set up and use the Sandbox environment

  <Info>
    If you need to test a sensitive action in the Sandbox environment, [follow this guide](https://docs.qonto.com/api-reference/business-api/authentication/sca/sca-flows#testing-a-sensitive-action-in-the-sandbox-environment).
  </Info>
</Accordion>

<Accordion title="Best practices for error handling and retries">
  ### **Understand the Limits**

  * 1,000 requests per 10 seconds & 10,000 requests per 10 minutes
  * Max. 200 requests with status 401 per hour
  * Limits are enforced per IP address
  * Exceeding limits returns a `429 Too Many Requests` error
  * Frequent 401 responses may lead to throttling

  ***

  ### **What to Expect from Qonto**

  * Qonto uses standard HTTP status codes:
    * **2xx**: Success
    * **4xx**: Client errors (e.g., invalid parameters, unauthorized)
    * **5xx**: Server errors (rare)
  * **Error response format**: Follows the [**JSON:API error object**](https://jsonapi.org/format/#error-objects). Example:

    ```
    {
      "errors": [
        {
          "code": "not_in_list",
          "detail": "status must be one of: pending, approved, declined",
          "source": {
            "parameter": "status"
          }
        }
      ]
    }
    ```
  * The error object includes:
    * `code`: Machine-readable error code (e.g., `not_in_list`)
    * `detail`: Human-readable explanation
    * `source.pointer`/`source.parameter`: Pinpoints the problematic part of your request

  ***

  ### **Best Practices for Handling Errors and Retries**

  #### **Handle 429 Errors Gracefully**

  * **Do not retry immediately**: When you receive a `429`, don’t immediately retry. Instead, implement exponential backoff (increase the wait time between retries).

      <Info>
        Example: Wait 1s, then 2s, then 4s, etc.
      </Info>
  * **Check for Retry-After header**: If the API provides a `Retry-After` header, always respect it before retrying.

  #### **Proactively Monitor Your Request Rate**

  * **Track your own usage**: Keep a count of requests sent in the last 10 seconds and last 10 minutes per IP.
  * **Throttle on the client side**: If you’re approaching the limit, slow down or queue requests before hitting the server.

  #### **Handle 401 Errors Carefully**

  * **Investigate authentication issues**: 401 errors mean unauthorized. Don’t blindly retry. Instead, check your credentials or token validity.
  * **Stop after repeated 401s**: If you get several 401s in a row, stop and investigate to avoid hitting the 200/hour limit and getting throttled.

  #### **Parse Error Responses Properly**

  * Always read the `code` and `detail` fields in the error response to understand the problem.
  * Use `source` pointers/parameters to locate exactly what caused the error in your request.

  #### **Log and Alert**

  * **Log all rate limit and auth errors**: This helps in debugging and in tuning your retry logic.
  * **Set up alerts** for sudden spikes in 401 or 429 errors.

  #### **Design Resilient Retry Logic**

  * **Limit total number of retries**: Don’t retry forever. Set a maximum retry limit per request.
  * **Randomize retry intervals**: To avoid “thundering herd” problems, add randomness (jitter) to your retry intervals.
</Accordion>

<Tip>
  Need to report a bug, request a new feature, or didn’t find your answer? [Click here.](https://getqonto.atlassian.net/servicedesk/customer/portals)
</Tip>