Error Codes

All error responses follow a consistent format with a machine-readable code and a human-readable message.

Error response format

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description",
    "details": {}
  }
}

Error code reference

Code	HTTP Status	Description	Action
VALIDATION_ERROR	400	Request parameters failed validation	Check query parameters match the expected types and ranges
MISSING_API_KEY	401	No X-API-Key header provided	Add the X-API-Key header to your request
INVALID_API_KEY	401	The API key is not recognised	Verify your API key is correct and active
FORBIDDEN	403	The API key is valid but access is denied	Contact support — your organisation may be disabled
COLLECTION_NOT_FOUND	404	The requested collection does not exist	Verify the collection ID is correct
INTERNAL_ERROR	500	An unexpected server error occurred	Retry after a short delay. Contact support if persistent.
BAD_GATEWAY	502	Upstream service error	Retry after a short delay. The upstream service may be temporarily unavailable.
SERVICE_UNAVAILABLE	503	Service temporarily unavailable	Internal service issue. Retry after a short delay, or check the status page or contact support.

Detailed examples

VALIDATION_ERROR

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": {
      "fields": [
        {
          "field": "page",
          "message": "Must be a non-negative integer"
        },
        {
          "field": "pageSize",
          "message": "Must be between 1 and 100"
        }
      ]
    }
  }
}

COLLECTION_NOT_FOUND

{
  "error": {
    "code": "COLLECTION_NOT_FOUND",
    "message": "Collection 'col_invalid' not found"
  }
}

BAD_GATEWAY

{
  "error": {
    "code": "BAD_GATEWAY",
    "message": "Error communicating with upstream service"
  }
}

SERVICE_UNAVAILABLE

{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Service temporarily unavailable"
  }
}

HTTP status code summary

Status	Description
200 OK	Request succeeded
304 Not Modified	Collection unchanged (conditional request)
400 Bad Request	Invalid request parameters
401 Unauthorized	Authentication required or failed
403 Forbidden	Access denied
404 Not Found	Resource not found
500 Internal Server Error	Unexpected server error
502 Bad Gateway	Upstream service error
503 Service Unavailable	Service temporarily unavailable