Error Format

All CueAPI errors follow a consistent JSON structure.

Error envelope

Every error response uses this structure:

json

{
  "error": {
    "code": "string",
    "message": "string",
    "status": 400
  }
}

Field	Type	Description
`code`	string	Machine-readable error code (e.g., `cue_not_found`)
`message`	string	Human-readable description
`status`	integer	HTTP status code

HTTP status codes

Code	Meaning
`400`	Bad request — invalid input
`401`	Unauthorized — missing or invalid API key
`403`	Forbidden — plan limit exceeded
`404`	Not found — resource doesn't exist
`409`	Conflict — duplicate or already exists
`413`	Payload too large — body exceeds 2 MB
`422`	Unprocessable — validation error (e.g., unknown fields)
`429`	Too many requests — rate limit exceeded
`500`	Internal server error
`502`	Bad gateway — upstream service error (e.g., Stripe)

Validation errors (422)

FastAPI/Pydantic validation errors use a different format:

json

{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "name"],
      "msg": "Field required",
      "input": {}
    }
  ]
}

Handling errors

python

response = requests.post(url, headers=headers, json=body)
 
if response.status_code >= 400:
    error = response.json().get("error", {})
    print(f"Error {error.get('code')}: {error.get('message')}")

Previous← FAQs NextError Codes →