Error Handling

Our system reports errors at two levels:

Standard HTTP Status Codes – Protocol-level issues such as invalid requests or server failures.
Business Logic Errors – Application-level validations and conditions reported within the response payload.

1) HTTP Status Codes

The API returns conventional HTTP status codes to indicate the result of a request. Below is a list of common status codes and their possible meanings:

Status Code	Description(s)
400 Bad Request	Invalid request parameters General malformed input
401 Unauthorized	Authorization failed Invalid or missing token
403 Forbidden	Invalid checksum Access to the resource is forbidden
404 Not Found	Original transaction not found Card not found
409 Conflict	Adjustment conflict (already processed) Reversal already processed Card already stopped Duplicate transaction detected
422 Unprocessable Entity	Invalid transaction type Partial reversal amount exceeds original amount Invalid or inconsistent parameters
500 Internal Server Error	General server failure Reversal processing error Unexpected internal error

💡
These errors should be handled at the protocol level by inspecting the response status code. The response body may also include additional details.

2. Business Logic Errors (ErrorWrapper)

Some errors are related to business rules or validation logic specific to UnDosTres operations. These are returned in the response body using a structured ErrorWrapper format, typically with an error.code and error.message.

Error Response Example

{
  "endpoint": "debit/v1/someErrorEndpoint",
  "error": {
    "Code": 5000,
    "Text": "Validation Error",
    "Hints": ["Check your input parameters and try again"],
    "Info": ""
  },
  "payload": {}, // O un objeto de payload de fallo
  "text": "Error",
  "timestamp": "2021-06-25T16:39:15.095Z"
}

Common Error Codes (sorted by code)

Code	Message
5000	Validation error
5001	Monthly transaction limit reached
5002	Wallet is inactive
5003	Insufficient balance
6000	Database error
7000	WAAS server error
8000	Device not linked to `token_refresh`, use `/get-customer-connection-token`
8001	Device is linked to `token_refresh`, use `/refresh-customer-token`
8002	Refresh token has expired
8003	Incomplete request data
8004	`extra_login_data` is required (missing)
8005	`extra_login_data` is required due to expired token
8006	Invalid parameter in refresh token
8007	User validation required
8008	E-commerce token has expired
8009	Invalid request data
8010	OAuth token has expired
8011	Generic error

Best Practices for Error Handling

Always check the HTTP status code of the response.

If a 4xx or 5xx error is returned, inspect the response body for details.
For business logic errors, use the error.code and error.message to implement precise error handling or user feedback.
Implement retry logic for 500 errors or transient conditions where appropriate.
Log unexpected errors to assist with debugging and support.