Error handling

Overview

Reservepay uses a standardized error format called Error Triples. When a request cannot be processed, the API returns a 400 Bad Request status code with a JSON array containing three elements: a machine-readable code, a human-readable message, and additional details.

The Error Triple

Every error response follows this exact structure:

[ERROR_CODE, ERROR_MESSAGE, ERROR_DETAILS]

When errors occur

The API only uses the 400 Bad Request status code for expected error conditions. This includes:

• Validation failures: Missing required fields or invalid data formats.
• Business logic errors: Insufficient funds, expired tokens, or invalid transitions.
• Authentication issues: Missing or invalid API keys.

If you receive any other status code (like 500 or 404), it indicates an unexpected system error or a routing issue rather than a handled API error.

Working with details

The third element of the triple, ERROR_DETAILS, provides context that varies depending on the error code.

For validation errors, it often contains an array of specific field issues:

[
  "INVALID_ARGUMENTS",
  "One or more of the supplied arguments are invalid",
  [
    {
      "type": "invalid",
      "argument": "month",
      "message": "Invalid format, expected YYYY-MM, got 12/2025"
    }
  ]
]

In other cases, such as a generic authentication failure, the details might be null:

[
  "UNAUTHORIZED",
  "Invalid API key provided.",
  null
]

Your error handling logic should check if details is present before attempting to parse it.

Common errors

While specific endpoints may define their own error codes, here are some you will encounter across the API: