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"
      }
    }
  ]
}
  • 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.

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"
      }
    }
  ]
}