Error Codes
These are the error codes that can be returned by the Wava API to external consumers. Each error follows the standard error format.
Authentication errors (1000-1099)
| Code | API Code | Message | Description |
|---|
| 1001 | MISSING_MERCHANT_KEY | Missing merchant-key header | The merchant-key header is required for API authentication |
| 1002 | INVALID_MERCHANT_KEY | Invalid merchant key | The provided merchant key is not valid or has been revoked |
| 1003 | UNAUTHORIZED_ACCESS | Unauthorized access | You do not have permission to access this resource |
| 1004 | INSUFFICIENT_SCOPE | Insufficient scope | You don’t have access to this resource |
Validation errors (2000-2099)
| Code | API Code | Message | Description |
|---|
| 2000 | VALIDATION_FAILED | Validation failed | One or more fields failed validation. Check the validation_errors array for details |
| 2001 | REQUIRED_FIELD_MISSING | Required field missing | One or more required fields are missing from the request |
| 2002 | INVALID_FIELD_FORMAT | Invalid field format | One or more fields have an invalid format |
| 2003 | AMOUNT_REQUIRED | Amount is required | The amount field is required and must be a positive number |
| 2004 | DESCRIPTION_REQUIRED | Description is required | The description field is required |
| 2005 | INVALID_CURRENCY | Invalid currency | Currency must be a valid 3-letter ISO code (e.g., COP) |
| 2006 | INVALID_EMAIL | Invalid email format | The email address provided is not in a valid format |
| 2007 | INVALID_PHONE | Invalid phone number | Phone number must contain only digits |
| 2008 | INVALID_URL | Invalid URL format | The URL provided is not in a valid format |
Order and store errors (3000-3099)
| Code | API Code | Message | Description |
|---|
| 3001 | STORE_NOT_FOUND | Store not found | The specified store does not exist |
| 3002 | STORE_INACTIVE | Store inactive | The store is not currently active |
| 3003 | ORDER_NOT_FOUND | Order not found | The specified order does not exist or you do not have access to it |
| 3004 | ORDER_ALREADY_PROCESSED | Order already processed | This order has already been processed and cannot be modified |
| 3005 | INVALID_ORDER_STATUS | Invalid order status | The order is not in a valid status for this operation |
| 3010 | DATA_NOT_FOUND | Data not found | The requested data could not be found |
| 3017 | INVALID_SORT_COLUMN | Invalid sort column | The specified column is not allowed for sorting |
| 3018 | REFUND_WINDOW_EXPIRED | Refund window expired | The refund period for this order has expired |
Payment errors (4000-4099)
| Code | API Code | Message | Description |
|---|
| 4001 | PAYMENT_GATEWAY_REQUIRED | Payment gateway required | A valid payment gateway must be provided |
| 4002 | PAYMENT_FAILED | Payment failed | The payment could not be processed |
| 4003 | INVALID_PAYMENT_AMOUNT | Invalid payment amount | The payment amount is invalid or does not match the order total |
| 4004 | PAYMENT_GATEWAY_NOT_SUPPORTED | Payment gateway not supported | The specified payment gateway is not supported by this store |
| 4005 | PAYMENT_GATEWAY_VALIDATION | Payment gateway validation failed | The payment gateway information provided is invalid or incomplete (e.g., missing phone for Nequi) |
Gateway-specific errors (6000+)
These errors originate from the payment gateway itself. The response will include a gateway_name field.
Nequi errors
| Code | API Code | Description |
|---|
| 6001 | NEQUI_PAYMENT_REJECTED | The buyer rejected the payment in the Nequi app |
| 6006 | NEQUI_TIMEOUT | The push notification expired before the buyer could approve it |
| 6007 | NEQUI_INSUFFICIENT_FUNDS | The buyer does not have enough balance in their Nequi account |
Daviplata errors
| Code | API Code | Description |
|---|
| 6101 | DAVIPLATA_INVALID_DOCUMENT | The national ID or document type is not valid for Daviplata |
| 6105 | DAVIPLATA_OTP_ERROR | Invalid or expired OTP code |
Server errors (5000-5099)
| Code | API Code | Message | Description |
|---|
| 5002 | SERVICE_UNAVAILABLE | Service temporarily unavailable | The service is temporarily unavailable, please try again later |
| 5003 | RATE_LIMIT_EXCEEDED | Rate limit exceeded | Too many requests, please slow down and try again later |
Gateway-specific errors (6000+) depend on the payment gateway and may include additional fields. Always check the gateway_name field to determine which gateway returned the error.
