Skip to main content
Errors return a consistent bilingual envelope with a machine-readable code, English and Arabic messages, a request id for support, and a docs link: 
{
  "error_code": "VALIDATION_ERROR",
  "message": "to must be a valid KSA phone number",
  "message_ar": "خطأ في التحقق من البيانات",
  "request_id": "req_abc123",
  "docs_url": "https://wave.sa/docs/errors"
}
Always branch on error_code (stable), not the message text.

​
HTTP statuses

StatusMeaning
400Validation error — check the request body.
401Missing or invalid API key.
403Sandbox trial expired, or the key lacks the required permission.
429Rate limit exceeded — see Rate limits.
5xxUpstream/telephony error — safe to retry with backoff.

​
Error codes

error_codeTypical statusMeaning
VALIDATION_ERROR400The request body failed validation.
INVALID_PHONE_NUMBER400to isn’t a valid KSA number.
INVALID_API_KEY401Missing, malformed, or unknown key.
INSUFFICIENT_PERMISSIONS403The key lacks the web_callback permission.
SANDBOX_EXPIRED403The 30-minute sandbox trial has elapsed.
SANDBOX_DESTINATION_NOT_ALLOWED403Sandbox calls may only ring the owner’s signup number.
RATE_LIMIT_EXCEEDED429More than 60 requests/minute — see Rate limits.
CALL_FAILED502The telephony backend could not place the call.
The complete code list (including OTP, webhook, session, and Nafath codes) is in the API Reference Error schema.

​
Request id

Every response carries a request_id. Include it when contacting support — it lets us find the exact request in the logs.