Errors

Error Format

All errors return a consistent JSON envelope:

{
  "statusCode": 400,
  "message": "limit must not be greater than 100",
  "error": "Bad Request"
}

The message field is always a human-readable string (or array of strings for validation errors). The error field is the HTTP status text.

Code	When returned
`200`	Successful GET / action that returns a body
`201`	Resource created (POST)
`204`	Successful DELETE or action with no response body

Code	Meaning
`400`	Bad Request — invalid query params or request body (validation failure)
`401`	Missing or invalid `x-api-key` header
`402`	Plan gate — this endpoint requires a Pro plan (e.g. AEO brand monitor)
`404`	Resource not found, or it belongs to a different organisation
`429`	Rate limit exceeded — back off and retry
`500`	Server error — retry with exponential backoff

401 vs 403: The API returns 401 for all authentication failures including an expired or revoked key. 403 is reserved for cases where the key is valid but the organisation lacks the required subscription.
404 scoping: Resources are always scoped to your organisation. A valid ID that belongs to another org returns 404, not 403.
429 headers: When rate-limited the response includes Retry-After (seconds) and X-RateLimit-Reset (Unix timestamp) headers.