Errors

In this guide, we will talk about what happens when something goes wrong while you work with the API. Mistakes happen - let's look at some status codes and error types you might encounter.

You can tell if your request was successful by checking the status code when receiving an API response. If a response comes back unsuccessful, you can use the error type and error message to figure out what has gone wrong and do some rudimentary debugging (before contacting support).

When you encounter an error, first check your request against the API reference to ensure all required parameters are included and correctly formatted. If the issue persists, contact Qonic support with the full error response and your request details.

Status codes

Here is a list of the different categories of status codes returned by the Qonic API. Use these to understand if a request was successful.

  • Name
    200
    Description
    The request succeeded. Response body contains the requested data.
  • Name
    201
    Description
    A new resource was created successfully. Response body contains the created resource.
  • Name
    204
    Description
    The request succeeded with no response body (typically for DELETE operations).
  • Name
    302
    Description
    Redirect. Returned by the OAuth authorization and consent endpoints during the authentication flow.
  • Name
    400
    Description
    The request was invalid. Check the error message for details on which parameters are missing or malformed.
  • Name
    401
    Description
    Authentication required. Provide a valid Bearer token in the Authorization header.
  • Name
    403
    Description
    You don't have permission for this operation. Check that your token has the required scopes.
  • Name
    404
    Description
    The requested resource was not found. Verify the resource ID exists and you have access to it.
  • Name
    500
    Description
    An unexpected server error occurred. If this persists, contact support.

Error response formats

The Qonic API uses two error response formats depending on the type of error.

Client errors (400, 403, 404)

Validation errors and business-logic rejections return an ErrorView object:

  • Name
    error
    Type
    string
    Description
    A machine-readable error code (e.g., InvalidArgument, MissingArgument, NotFound, Forbidden).
  • Name
    errorDetails
    Type
    string
    Description
    A human-readable message explaining what went wrong.

Authentication errors (401)

Authentication failures return a ProblemDetails object (RFC 9457):

  • Name
    type
    Type
    string
    Description
    A URI reference identifying the problem type (typically an RFC 9110 section).
  • Name
    title
    Type
    string
    Description
    A short summary of the problem (e.g., Unauthorized).
  • Name
    status
    Type
    integer
    Description
    The HTTP status code.
  • Name
    detail
    Type
    string
    Description
    A human-readable explanation specific to this occurrence of the problem. May be absent.
  • Name
    instance
    Type
    string
    Description
    A URI reference identifying the specific occurrence of the problem. May be absent.
  • Name
    traceId
    Type
    string
    Description
    The distributed-trace identifier for the request (W3C traceparent format). Include this value when contacting support so we can locate the request.
‹
Previous
Authentication
›
Next
Auth API