Errors

All error responses are returned as JSON.

Error response types

The API returns one of three common error shapes.

HTTP errors

Standard HTTP errors return a short message in the error field.

404 Not Found

{
  "error": "Not Found"
}

Validation errors

Request validation errors return 422 Unprocessable Entity with a structured detail array.

422 Unprocessable Entity

{
  "error": "Invalid request",
  "detail": [ 
    { 
      "field": "images.0.url", 
      "message": "Field required", 
      "in": "body"
    } 
  ] 
}

Each item in detail includes:

Field	Description
`field`	Dot path to the invalid value
`message`	Human-readable validation message
`in`	Request location where validation failed: `query`, `body`, `form`, or `path`

Internal errors

Unexpected failures return 500 Internal Server Error with a generic message and a reference code.

500 Internal Server Error

{
  "error": "An internal error occurred.",
  "reference": "a1b2c3d4"
}

Reference codes help map a client-visible error to server-side logs without exposing internal details.

If you contact support about a 500 error, include the reference value from the response.

Handling errors in code

The example below shows one way to parse known error response shapes.

import requests

def read_api_error(response: requests.Response) -> str:
    try:
        payload = response.json()
    except ValueError:
        return f"HTTP {response.status_code}: unexpected non-JSON error"

    if response.status_code == 422 and "detail" in payload:
        first = payload["detail"][0] if payload["detail"] else {}
        location = first.get("in", "body")
        field = first.get("field", "unknown")
        message = first.get("message", "Invalid request")
        return f"Validation error ({location}.{field}): {message}"

    if response.status_code >= 500 and "reference" in payload:
        return f"Server error. Reference code: {payload['reference']}"

    return payload.get("error", f"HTTP {response.status_code} error")