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
    422
    Description
    The request could not be processed because of validation or malformed input. Correct the invalid fields described by the response, then submit a valid request.
  • Name
    429
    Description
    Too many requests. Wait before retrying; honor Retry-After when present, otherwise retry with backoff.
  • Name
    500
    Description
    An unexpected server error occurred. If this persists, contact support.

Error response formats

Error response schemas are endpoint-specific. Check the error responses in the relevant API-reference operation: an endpoint can document either ErrorView or ProblemDetails, so do not infer the response body from the status code alone.

Endpoints that document ErrorView

For endpoints that document ErrorView, validation and business-logic failures return this 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.

Endpoints that document ProblemDetails

For endpoints that document ProblemDetails, parse this RFC 9457-compatible object:

  • 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