Errors

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

Status	Meaning
`400`	Validation error — check the request body.
`401`	Missing or invalid API key.
`403`	The project’s sandbox minutes are used up, or the key lacks the required permission.
`429`	Rate limit exceeded — see Rate limits.
`5xx`	Upstream/telephony error — safe to retry with backoff.

Error codes

`error_code`	Typical status	Meaning
`VALIDATION_ERROR`	400	The request body failed validation.
`INVALID_PHONE_NUMBER`	400	`to` isn’t a valid KSA number.
`INVALID_API_KEY`	401	Missing, malformed, or unknown key.
`INSUFFICIENT_PERMISSIONS`	403	The key lacks the `web_callback` permission.
`SANDBOX_MINUTES_EXCEEDED`	403	The project used its 15 sandbox minutes. A real sandbox call is refused. Simulated calls still work. See Sandbox mode.
`RATE_LIMIT_EXCEEDED`	429	More than 60 requests/minute — see Rate limits.
`CALL_FAILED`	502	The 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 the request id in the x-request-id response header. An error response also carries it in the body as request_id (the same value). A browser client can read the header (it is exposed through CORS). Use the id to find the request in the portal Request log, and include it when contacting support — it lets us find the exact request in the logs.

Get Started

Voice

Web Callback

WhatsApp

Reference

HTTP statuses

Error codes

Request id

​HTTP statuses

​Error codes

​Request id

HTTP statuses

Error codes

Request id