Error Handling¶

All API errors follow a consistent JSON envelope structure.

Error Response Format¶

{
  "code": 0,
  "message": "Error http: {status_code}",
  "detail": "Description of the error",
  "extra_info": {}
}

Field	Type	Description
`code`	Integer	Internal error code
`message`	String	HTTP status identifier, e.g. `"Error http: 400"`
`detail`	String	Human-readable error description
`extra_info`	Object	Additional context (optional)

HTTP Status Codes¶

Status	Meaning	Common Causes
`400`	Bad Request	Invalid parameters, rejected payment, business rule violation
`401`	Unauthorized	Invalid or expired credentials / auth token
`403`	Forbidden	Insufficient permissions
`404`	Not Found	Resource does not exist
`422`	Validation Error	Request body failed schema validation
`500`	Internal Server Error	Unexpected server error

Validation Errors (422)¶

When the request body fails validation, the API returns field-specific error messages:

{
  "code": 0,
  "message": "Error http: 422",
  "detail": "El campo 'amount' es requerido\nEl campo 'hotel_id' no es un número entero válido\n"
}

Validation Error Messages¶

Error Type	Message
Missing required field	`El campo '{field}' es requerido`
String too short	`El campo '{field}' debe tener al menos {n} caracteres`
String too long	`El campo '{field}' no puede tener más de {n} caracteres`
Not a number	`El valor en el campo '{field}' no es un número válido`
Invalid value	`El valor en el campo '{field}' es inválido`
Invalid enum	`El valor en el campo '{field}' no está entre los valores permitidos`
Null not allowed	`El valor 'null' no está permitido en el campo '{field}'`

Payment Error Responses¶

Payment endpoints may include additional context in extra_info:

{
  "code": 0,
  "message": "Error http: 400",
  "detail": "El pago ha sido rechazado",
  "extra_info": {
    "voucher_url": "v2/terminal-payments/481/vouchers",
    "details": {
      "type": "charge",
      "status_code": "rejected",
      "status_detail": "Rechazado",
      "comments": "Fondos insuficientes."
    }
  }
}

Best Practices

Always check the HTTP status code first, then parse the response body.
For payment operations, check status_code inside details for the definitive payment status.
Implement retry logic for 500 errors with exponential backoff.
Do not retry 400, 401, 403, or 422 errors.