Errors

This page describes the error responses you should expect when integrating the SERVOS API.

Every error the API returns has the same shape: error is a message in English, and details is an object with the specifics behind it, empty when there are none. The 422 messages are written for guests and can be shown as they are.

{
  "error": "Too many requests; slow down and retry after the window",
  "details": {}
}

A few failures are answered before the API runs and may not be JSON: an unexpected server error (500), a path that matches no endpoint (for example an id that is not a UUID), and a request body that is not valid JSON. Rely on the status code for those.

400 Bad Request

Returned when required parameters are missing, have an unsupported value, or cannot be parsed.

Missing required parameter

{ "error": "param is missing or the value is empty or invalid: service_id", "details": {} }

Unknown cart item type

{ "error": "Unknown cart item type: voucher", "details": {} }

Invalid date format

{ "error": "Invalid date format: invalid date", "details": {} }

Invalid date range

Some endpoints validate date ranges and may return:

{ "error": "Date range cannot exceed 90 days", "details": {} }

401 Unauthorized

Returned when the API key is missing or invalid.

{ "error": "Invalid or missing API key", "details": {} }

404 Not Found

Returned when a resource does not exist or is not publicly visible.

{ "error": "Not found", "details": {} }

422 Unprocessable Entity

Returned when the request is syntactically valid, but the operation cannot be performed.

This is common when attempting to add an unavailable item to a cart.

Item unavailable

details says what was unavailable, naming records by the same ids the rest of the API uses. For example, how many tickets are left:

{
  "error": "Only 2 General tickets left",
  "details": {
    "ticket_variant_id": "6f1c2a9e-3b7d-4e1a-9c5f-2d8b4a7e6c31",
    "ticket_variant_name": "General",
    "requested_quantity": 3,
    "available_quantity": 2
  }
}

Invalid fields

details lists the messages for each field:

{
  "error": "Check out must be greater than 2026-10-02",
  "details": {
    "check_out": ["must be greater than 2026-10-02"]
  }
}

429 Too Many Requests

Returned when an API key exceeds its request budget. Wait for the number of seconds in the Retry-After header before retrying.

{
  "error": "Too many requests; slow down and retry after the window",
  "details": {}
}