API Usage & Best Practices

Rate limits: What are they and how to handle them?

How to test integrations in Sandbox?

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. 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).
Example: Wait 1s, then 2s, then 4s, etc.
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.

Support

API Usage & Best Practices

What are rate limits?

How to handle them at Qonto?

Understand the Limits

What to Expect from Qonto

Best Practices for Handling Errors and Retries

Handle 429 Errors Gracefully

Proactively Monitor Your Request Rate

Handle 401 Errors Carefully

Parse Error Responses Properly

Log and Alert

Design Resilient Retry Logic