Errors

Wave’s bilingual error envelope, error codes, and HTTP statuses.

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	Sandbox trial expired, 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_EXPIRED	403	The 30-minute sandbox trial has elapsed.
SANDBOX_DESTINATION_NOT_ALLOWED	403	Sandbox calls may only ring the owner’s signup number.
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 a request_id. Include it when contacting support — it lets us find the exact request in the logs.