Client APIs

# Error responses

Error responses from the API are designed to provide comprehensive information to help clients understand the cause of an error and resolve it autonomously.

# Error response format

All error messages use a consistent format across all endpoints.

{
  "request_id": "{request_id}",
  "error": {
    "code": "{error_code}",
    "message": "{error_message}",
    "documentation": "{error_documentation}",
    "details": "{error_details}"
  }
}
  • request_id: The request ID in UUID v4 format, assigned by the API to the request.
  • error_code: A composite code formatted as {http_error_code}-{api_error_code} (e.g., 404-D4E). The HTTP error code (opens new window) indicates the type of error, while the second part specifies the exact issue. Always include the full error code when contacting support.
  • error_message: A brief error message, generally aligned with the HTTP status message (opens new window). This message is suitable for display to end-users alongside the error code. Examples of messages are Bad Request, Not Found, Configuration issue, Service Not Available, etc.
  • error_documentation: An extended description providing more context and actions to resolve the issue. This part of the error response should not be shared with end-users. This message is intended for technical teams and should not be exposed to end-users. May not always be in the error response.
  • error_details: Details about the parameters that caused the error, like a value or list of values. Most errors don't include details in their response.

Important

Ensure all fields in the error message are processed and logged by the client system. These details should be provided when contacting support.

# Example of an error response

In the scenario where a voucher issuance request fails due to a missing Idempotency-Key header, the following error message is returned:

{
  "request_id": "2bec0acd-55f2-4465-9cff-690b0dbefb62",
  "error": {
    "code": "400-9A0",
    "message": "Bad Request",
    "documentation": "Idempotency-Key header is required for this route, please refer to the OpenAPI specification."
  }
}
  • request_id: 2bec0acd-55f2-4465-9cff-690b0dbefb62 - This ID allows the support team to locate the specific event in the logs.
  • code: 400-9A0 - The 400 indicates a Bad Request, meaning the issue comes from the client's request format or parameters. The 9A0 is used internally for more detailed troubleshooting.
  • message: Bad Request - Corresponds to the HTTP 400 error, indicating that the request could not be processed due to a client error.
  • documentation: This message details that the Idempotency-Key header is required and missing.

← List of errors →