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 (location, message, type).

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."
}