Troubleshooting & Error Codes

General errors

How to debug 4XX & 500 errors?

Qonto follows industry best practices for error handling using the JSON:API error object format. Here’s how to effectively debug these errors:

Understanding HTTP Status Codes

4XX Errors (Client Errors):

Represent errors where the request could not be processed due to issues with the provided information
Examples: missing parameters, invalid data, authentication issues

5XX Errors (Server Errors):

Indicate server-side errors at Qonto (these are rare)

Usually temporary issues on Qonto’s side

Debugging Best Practices

Check the error details: Always examine the code and detail fields for specific guidance
Use source information: The source.pointer and source.parameter fields help identify exactly what’s wrong
Verify authentication: Ensure proper tokens and headers are included
Check API documentation: Verify endpoint URLs, required parameters, and request formats
For sandbox testing: Always include the X-Qonto-Staging-Token header
Handle bulk operations: For endpoints like bulk transfers, use the client_transfer_id to identify which specific transfer failed

Specific Troubleshooting Tips

OAuth issues: Check refresh token usage, ensure proper scopes, verify redirect URIs
Pagination limits: Split large requests into smaller batches using filters
CSRF errors: Check cookie handling and avoid parallel OAuth flows
HTML responses: Usually indicates missing staging token in sandbox environment

How to debug a '404 Not Found' error?

There is probably a mistake in the url you are calling (ex: you are trying to call /v2/organizations instead of /v2/organization), cf. the API reference to verify if the url you are calling is correct.

I'm getting an HTML response with a '200' sucess status / I'm redirected to 'https://qonto.onelogin.com/login'

Error

<!doctype html>
<html lang="en" style="height: 100%">

<head>
    <meta charset="utf-8">
    <meta http-equiv="x-ua-compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
    <meta name="theme-color" content="#000000">
    <meta name="robots" content="noindex,nofollow">
    <link rel="shortcut icon" href="https://web-login-v2-cdn.onelogin.com/login2/favicon.ico">

    <script type="text/javascript"
        src="https://cdn.cookielaw.org/consent/acac541d-dd27-479c-854b-d21d620c7af5/OtAutoBlock.js"></script>
    <script type="text/javascript">
        window.thisdata = { options: {} };
    </script>
    <script type="text/javascript" src="https://cdn.onelogin.com/onelogin-vigilance.min.js" async=true></script>
    <title>OneLogin</title>

    <!--[if lt IE 9]>
    <style>
    .withConditionalBorder {
        border-width: 1px;
        border-style: solid;
        border-color: #e8eaeb;
    }
    </style>
    <![endif]-->

</head>

<body
    style="padding: 0; margin: 0; height: 100%; font-family: Roboto, 'Helvetica Neue', Helvetica, 'Segoe UI', Arial, sans-serif;">
    <noscript>
        You need to enable JavaScript to run this app.
    </noscript>
    <div id="root" style="height: 100%"></div>

    <!--[if lt IE 10]>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv.js"></script>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/es5-shim/4.5.7/es5-shim.min.js"></script>
    <script src="https://cdn.polyfill.io/v2/polyfill.min.js?features=Intl.~locale.en"></script>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/json3/3.3.0/json3.min.js"></script>
    <script type="text/javascript" src="https://web-login-v2 cdn.onelogin.com/login2/vendor-es31648af8d2886e977b6cf434196ca0aef1fb7fa38.js"></script>
    <script type="text/javascript" src="https://web-login-v2-cdn.onelogin.com/login2/intl-es31648af8d2886e977b6cf434196ca0aef1fb7fa38.js"></script>
    <script type="text/javascript" src="https://web-login-v2-cdn.onelogin.com/login2/app-es31648af8d2886e977b6cf434196ca0aef1fb7fa38.js"></script>
<![endif]-->

    <!--[if gte IE 10 | !IE ]><!-->
    <script type="text/javascript"
        src="https://web-login-v2-cdn.onelogin.com/login2/vendor1648af8d2886e977b6cf434196ca0aef1fb7fa38.js"></script>
    <script type="text/javascript"
        src="https://web-login-v2-cdn.onelogin.com/login2/intl1648af8d2886e977b6cf434196ca0aef1fb7fa38.js"></script>
    <script type="text/javascript"
        src="https://web-login-v2-cdn.onelogin.com/login2/app1648af8d2886e977b6cf434196ca0aef1fb7fa38.js"></script>
    <![endif]-->
</body>
</html>

Solution

Add your X-Qonto-Staging-Token (available in the Developer Portal) in the header of your API call.

I'm getting a CORS error

Error

Access to XMLHttpRequest at `qonto_endpoint_url` from origin `browser_url` has been blocked by CORS policy: Response to preflight request doesn't pass access control check: No 'Access-Control-Allow-Origin' header is present on the requested resource.

Solution

For security reasons, direct API requests from browsers are not allowed. You must perform your API requests via a backend proxy.

Issues regarding Business API

I'm getting a CSRF error in my OAuth redirect URI

Error

The request is not allowed. No CSRF value available in the session cookie

Solution

Here are the common causes for CSRF error:

Cookie is not being properly passed/stored in the browser;
The consent app is not properly passing back the CSRF token in the redirect;
Multiple parallel auth flows interfering with each other’s cookies (user might have started the OAuth flow in two browsers or tabs);
Browser security settings blocking or clearing the cookies.

The token endpoint doesn’t return a refresh token

Use the offline_access scope when retrieving an authorization code.

I'm getting a '40X' error when calling the refresh token endpoint

Error

API response

    {
    "error": "invalid_grant",
    "error_description": "The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client.",
    "status_code": 400
    }

    {
        "error":"token_inactive",
        "error_description":"Token is inactive because it is malformed, expired or otherwise invalid. Token validation failed."
        "status_code": 401
    }

Our API implements automatic reuse detection for refresh tokens to prevent potential security vulnerabilities. This ensures that refresh tokens are not used multiple times simultaneously, which could compromise security.For more detailed information on this mechanism, you can refer to Auth0’s documentation on automatic reuse detection, which outlines the principles and benefits of this approach.

Solution

2 common use cases :

You are trying to refresh a token that has already been refreshed. When a refresh token is used twice all the refresh tokens belonging to the same consent are invalidated.
A new OAuth consent has been given in the meantime. This is invalidating the refresh token of the previous consent.

You should ask for a new OAuth consent in order to get a new refresh token.Don’t forget to store the new refresh_token as they are one time use.

I'm redirected to One Login when I'm triggering the OAuth flow (Login endpoint)

Need to report a bug, request a new feature, or didn’t find your answer? Click here.

Other issues

I don't manage to create a connection between Make / Zapier and the Qonto Sandbox account

Unfortunately, it’s not possible to create a native connection between a No-Code tool and Qonto Sandbox i.e. you can only create a native connection with a Qonto Production account. However, you could establish a connection with Qonto Sandbox by using the HTTP brick (OAuth or API key depending on your needs).

I'm getting a '422 search_limit_reached' error when calling the transactions endpoint

Error

    {
        "errors": [
            {
                "code": "search_limit_reached",
                "detail": "pagination is invalid. Search limit of 10000 transactions reached. Please use a smaller filter set.",
                "source": {
                    "pointer": "/pagination"
                }
            }
        ]
    }

Solution

You should check the total_pages / total_count fields in the meta object received in the response (when calling the first page). If the total_pages > 100 or the total_count > 10 000, it means that you’ll have to split the initial request in batches by using filters.To do so, this is what we suggest:

Call the first page with the default sorting.
Get the value of the settled_at field of the first transaction : let’s call it end_date
Call the first page with the following sorting parameter : asc
Get the value of the settled_at field of the first transaction : let’s call it start_date
Let’s say that :
- number_of_batches = total_count / 10 000 → round it up (ex: if you get 1.3, the number of batches will be 2)
- initial_period = end_date - start_date = X seconds
- nb_of_seconds_per_bacth = initial_period / number_of_batches
Call the /v2/transactions endpoint number_of_batches times by applying the settled_at_from and settled_at_to filters:
- First batch: settled_at_from = start_date & settled_at_to = start_date + nb_of_seconds_per_period
- n-th batch: settled_at_from = start_date + (n-1) x nb_of_seconds_per_period & settled_at_to = start_date + n x nb_of_seconds_per_period
- Last batch: settled_at_from = end_date - nb_of_seconds_per_period & settled_at_to = end_date

Support

​General errors

​Understanding HTTP Status Codes

​Debugging Best Practices

​Specific Troubleshooting Tips

​Error

​Solution

​Error

​Solution

​Issues regarding Business API

​Error

​Solution

​Error

​Solution

​Other issues

​Error

​Solution

General errors

Understanding HTTP Status Codes

Debugging Best Practices

Specific Troubleshooting Tips

Error

Solution

Error

Solution

Issues regarding Business API

Error

Solution

Error

Solution

Other issues

Error

Solution