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 |
| 3026 | WALLET_NOT_FOUND | Wallet not found | The wallet_id provided does not belong to this merchant |
| 3037 | WALLET_NOT_ACTIVE | Wallet is not active | The wallet_id provided is a suspended or closed wallet; only active wallets can receive payments |
| 3038 | CURRENCY_MISMATCH | Currency mismatch | The wallet_id provided is a wallet in a different currency than the resource it is being bound to |
| 3056 | ORDER_KEY_CONFLICT | order_key already belongs to an order with a different amount or currency | HTTP 409. A direct order with this order_key already exists on this store for another amount or currency. The response carries existing_amount and existing_currency. Use a unique order_key per order. |
| 3057 | INVALID_CHECK_DIGIT | Invalid check digit | HTTP 422. The check digit (DV) of a Colombian NIT or cédula does not match the number. The response carries expected_check_digit. Verify the number against the RUT. |
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 agateway_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.