Errors

At Qonto, we adhere to industry best practices for error handling, following the JSON:API error object format to provide clear, consistent, and actionable error responses for all API interactions.

We use conventional HTTP response codes to communicate the success or failure of an API request. In general:

• 2xx codes indicate a successful request.
• 4xx codes represent errors where the request could not be processed due to issues with the provided information (e.g., missing parameters, invalid data, etc.).
• 5xx codes indicate server-side errors at Qonto (these are rare).

Error Response Format

All error responses in our API follow the JSON:API error object format. The structure of the error object includes the following fields:

{
  "errors": [
    {
      "code": "string",
      "detail": "string",
      "source": {
        "pointer": "string",
        "parameter": "string"
      }
    }
  ],
  "trace_id": "string"
}

• code: A machine-readable code identifying the error, such as not_in_list.
• detail: A more detailed human-readable description of the error, useful for debugging or for the client to understand the exact issue.
• source.pointer (optional): The property in the request body that caused the error. This is helpful for pointing directly to the faulty part of the request body.
• source.parameter (optional): The query parameter that caused the error. This is useful when the issue is related to a specific query parameter.
• trace_id: A trace identifier for the request. It is always included in error responses and matches the X-Tyk-Trace-Id response header. Use it when reporting failures to Qonto support.

Example Response

Here’s an example of how an error response might look when you make an invalid request GET thirdparty.qonto.com/v2/transactions?status=invalid

{
  "errors": [
    {
      "code": "not_in_list",
      "detail": "status must be one of: pending, approved, declined",
      "source": {
        "parameter": "status"
      }
    }
  ],
  "trace_id": "6f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c"
}

Reporting Failing Requests

When contacting Qonto support about a failing API request, include a trace identifier so the Qonto team can locate the exact request in our systems and troubleshoot faster. You can use either of the following—they always match on error responses:

1. The X-Tyk-Trace-Id response header (present on every API response):

X-Tyk-Trace-Id: 6f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c

2. The trace_id field in the JSON body of the error response (always included for errors). This is often easier to copy from the response body than from headers:

{
  "errors": [ ... ],
  "trace_id": "6f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c"
}

Include either the X-Tyk-Trace-Id header value or the trace_id from the JSON body whenever you open a support request or report an issue. Both are present on error responses and identify the same request. Without one of them, tracing a specific failing request is significantly harder.