Errors

Most handler errors return a JSON envelope with a machine-readable code, a short message, and optional details.

{
  "code": "validation_error",
  "message": "Email is required",
  "details": null
}

Authentication failures from middleware return:

{
  "code": "authentication_error",
  "message": "unauthorized",
  "details": null
}

Some OpenAPI-generated validation failures use the Fuego HTTPError shape:

{
  "status": 400,
  "title": "Bad Request",
  "detail": "validation or deserialization error",
  "errors": [
    { "name": "email", "reason": "required" }
  ]
}

Common status codes

Code	Meaning
`400`	Bad request, malformed body, or validation failure
`401`	Missing or invalid authentication
`403`	Authenticated user is not allowed to perform the action
`404`	Resource was not found
`409`	Request conflicts with existing state
`422`	Request is valid JSON but invalid for the resource state
`429`	Rate limit exceeded
`500`	Server error

Examples

Missing authentication

curl https://api.getpaidhq.com/api/customers

{
  "code": "authentication_error",
  "message": "unauthorized",
  "details": null
}

Invalid subscription state

PUT /api/subscriptions/sub_123/cancel

{
  "code": "validation_error",
  "message": "Cannot cancel subscription in its current state",
  "details": null
}

Client handling

Branch first on HTTP status, then on code when present. Treat unknown 5xx responses as retryable only when the operation is idempotent.