Error reference

JSON shapes

Many domain errors use:

{
  "error": "service_not_found",
  "message": "Service not found."
}

Validation problems from the framework use:

{
  "error": "validation_error",
  "detail": []
}

where detail is an array of field-level issues carrying exactly three fields: loc (location), msg (message) and type.

The value you submitted is never returned. Earlier responses also included pydantic's input and ctx keys, which held the rejected value itself - and, for a missing-field error, the entire request body. Both are now stripped, and any message that would quote the submitted value is replaced with Invalid value. If you were relying on input to tell the user what they typed, read it from your own form state instead; the API will not echo it back.

note

components.schemas.ValidationError in the OpenAPI document still lists input and ctx. That schema is generated by the framework from pydantic's error model rather than from the handler that builds the response, so it over-lists two fields the API does not send. The shape documented above is the one to code against.

Error codes

Code	HTTP	Description
invalid_api_key	401	API key missing or invalid
service_not_found	404	Catalog slug does not exist
domain_not_found	404	Domain has no matching brand
query_too_short	422	Search query must be at least 2 characters
invalid_svg	400	SVG failed sanitization
duplicate_email	409	Email already registered
invalid_credentials	401	Wrong email or password
invalid_token	401	JWT missing, malformed, or expired
weak_password	422	Password does not meet requirements
billing_error	400	Billing provider error
maintenance	503	API temporarily unavailable
internal_error	500	Unexpected server error

Maintenance mode

When maintenance is active, non-health routes may respond with 503:

{
  "error": "maintenance",
  "message": "The API is temporarily unavailable for maintenance.",
  "retry_after": "Please try again in a few minutes."
}