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.

Getting Started

Orders

Payment Flows

Payment Links

Partners

Webhooks

Integrations

Testing

Error Handling

Error Codes

Error Codes

Authentication errors (1000-1099)

Validation errors (2000-2099)

Order and store errors (3000-3099)

Payment errors (4000-4099)

Gateway-specific errors (6000+)

Nequi errors

Daviplata errors

Server errors (5000-5099)

​Error Codes

​Authentication errors (1000-1099)

​Validation errors (2000-2099)

​Order and store errors (3000-3099)

​Payment errors (4000-4099)

​Gateway-specific errors (6000+)

​Nequi errors

​Daviplata errors

​Server errors (5000-5099)

Error Codes

Authentication errors (1000-1099)

Validation errors (2000-2099)

Order and store errors (3000-3099)

Payment errors (4000-4099)

Gateway-specific errors (6000+)

Nequi errors

Daviplata errors

Server errors (5000-5099)