Skip to main content

Error Handling

All Wava API errors return a consistent JSON structure:

Error fields

Validation error example

When validation fails (code 2000 or 4005), the response includes an array of field-specific errors:

Gateway error example

When a payment gateway returns an error, the response includes the gateway name:

HTTP status codes

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.