Troubleshooting & Error Codes
General errors
How to debug 4XX & 500 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
- Indicate server-side errors at Qonto (these are rare)
Debugging Best Practices
- Check the error details: Always examine the
codeanddetailfields for specific guidance - Use source information: The
source.pointerandsource.parameterfields 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-Tokenheader - Handle bulk operations: For endpoints like bulk transfers, use the
client_transfer_idto 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?
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'
I'm getting an HTML response with a '200' sucess status / I'm redirected to 'https://qonto.onelogin.com/login'
Detailed issue
Solution
Add yourX-Qonto-Staging-Token (available in the Developer Portal) in the header of your API call.
Issues regarding Business API
I'm getting a CSRF error in my OAuth redirect URI
I'm getting a CSRF error in my OAuth redirect URI
Issue
“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
The token endpoint doesn’t return a refresh token
Use the
offline_access scope in the login endpoint.I'm getting a '40X' error when calling the refresh token endpoint
I'm getting a '40X' error when calling the refresh token endpoint
Detailed issue
API responseSolution
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.
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)
I'm redirected to One Login when I'm triggering the OAuth flow (Login endpoint)
Please make sure to be logged in on the Sandbox web-app before calling the Login endpoint on the Sandbox environment.N.B.: this is a temporary process while we are migrating our OIDC step from OneLogin to the Developer Portal.
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
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
I'm getting a '422 search_limit_reached' error when calling the transactions endpoint
Detailed issue
Solution
You should check thetotal_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_atfield of the first transaction : let’s call itend_date - Call the first page with the following sorting parameter :
asc - Get the value of the
settled_atfield of the first transaction : let’s call itstart_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 secondsnb_of_seconds_per_bacth=initial_period/number_of_batches
- Call the /v2/transactions endpoint
number_of_batchestimes by applying thesettled_at_fromandsettled_at_tofilters:- 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) xnb_of_seconds_per_period&settled_at_to=start_date+ n xnb_of_seconds_per_period - Last batch:
settled_at_from=end_date-nb_of_seconds_per_period&settled_at_to=end_date
- First batch: