API Usage & Best Practices

​

What are rate limits?

• 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?

• 1 000 requests / 10 seconds
• 10 000 requests / 10 minutes

• 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

​

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.