Skip to main content

​
Error Handling

All Wava API errors return a consistent JSON structure: 
{
  "code": 4001,
  "api_code": "PAYMENT_GATEWAY_REQUIRED",
  "message": "Payment gateway is required",
  "description": "A payment gateway must be specified",
  "error": true
}

​
Error fields

FieldDescription
codeNumeric error code
api_codeMachine-readable error identifier
messageShort human-readable message
descriptionDetailed explanation
errorAlways true for error responses
gateway_namePresent for gateway-specific errors (6000+)
validation_errorsArray of field-level errors (for validation failures)

​
Validation error example

When validation fails (code 2000 or 4005), the response includes an array of field-specific errors: 
{
  "code": 2000,
  "api_code": "VALIDATION_FAILED",
  "message": "Validation failed",
  "description": "One or more fields failed validation",
  "error": true,
  "validation_errors": [
    {
      "field": "shopper.email",
      "message": "Invalid email format",
      "value": "not-an-email"
    },
    {
      "field": "amount",
      "message": "Amount is required",
      "value": null
    }
  ]
}

​
Gateway error example

When a payment gateway returns an error, the response includes the gateway name: 
{
  "code": 6105,
  "api_code": "DAVIPLATA_OTP_ERROR",
  "message": "Invalid or expired OTP",
  "description": "The OTP code provided is invalid or has expired",
  "error": true,
  "gateway_name": "daviplata"
}

​
HTTP status codes

StatusMeaning
200Success
202Accepted (refund processing)
400Bad request / Validation error
401Unauthorized (invalid or missing credentials)
404Resource not found
422Unprocessable (e.g., refund window expired)
429Rate limit exceeded
500Server error
503Service temporarily unavailable

​
Best practices

  • Always check the HTTP status code first.
  • Use api_code for programmatic error handling (not message, which may change or be localized).
  • For 400 errors, check the validation_errors array for field-specific issues.
  • For 500 and 503 errors, retry with exponential backoff.
  • For gateway errors (6000+), check gateway_name to determine which gateway returned the error and handle accordingly.