Errors

This guide describes how the Oxygen API communicates errors and what to expect when a request cannot be processed successfully. While errors are a normal part of working with any API, they are most often the result of invalid input, missing data, or incorrect configuration. Understanding error responses will help you diagnose and resolve issues efficiently.

Each API response includes an HTTP status code that indicates whether the request was successful. When a request fails, the status code and accompanying error message provide valuable information about the cause of the failure and how it can be addressed.

TIP

Before contacting support, we strongly recommend verifying your request payload, authentication credentials, and endpoint URLs. The majority of issues can be resolved by reviewing these areas. If the problem persists after troubleshooting, our support team will be happy to assist.

Status codes

The Oxygen API uses standard HTTP status codes to indicate the outcome of each request. The following categories will help you quickly assess the result of an API call.

Status Code	Description
2xx	A 2xx status code indicates that the request was processed successfully.
4xx	A 4xx status code indicates a client-side error, usually caused by invalid input, missing parameters, or incorrect request formatting.
5xx	A 5xx status code indicates a server-side error, meaning the Oxygen service encountered an internal issue while processing the request.

Validation errors

If a request fails due to invalid or missing input fields, the Oxygen API returns a response with status code 422. The response includes a general error message along with a detailed list of validation errors, allowing you to identify and correct each issue precisely.

{
    "message": "Invalid project reference format.",
    "errors": {
        "project_reference": [
            "Invalid project reference format."
        ],
        "buyer.tax_scheme.0.company_id": [
            "The buyer.tax_scheme.0.company_id field is required."
        ],
        "delivery.location.address.country": [
            "The delivery.location.address.country field must be 2 characters.",
            "The selected delivery.location.address.country is invalid."
        ]
    }
}