Sandbox mode

Sandbox keys (sk_sandbox_) place real calls, but under guardrails designed for safe testing.

Trial window

The sandbox trial clock starts on your first API call and runs for 30 minutes. After it expires, callback requests return 403 with error_code: SANDBOX_EXPIRED. The dashboard shows a live countdown.

Destination lock

To prevent abuse, sandbox calls can only ring the org owner’s signup phone number — the number verified at sign-up. A callback to any other to returns 403 with error_code: SANDBOX_DESTINATION_NOT_ALLOWED. Calling arbitrary destinations requires the production upgrade (coming soon).

Test numbers & simulated errors

Force specific outcomes without depending on a live call, in two ways. The header wins if both apply. Reserved test number

Number	Result
`+966500000017`	Simulated `server_error`

The x-wave-simulate header Set x-wave-simulate on POST /v1/callback to force an error variant (sandbox keys only — production ignores it):

Value	Simulates
`rate_limit`	Rate-limit rejection
`invalid_queue`	Unknown queue
`queue_unavailable`	Queue temporarily unavailable
`server_error`	Upstream/telephony failure
`invalid_number`	Invalid destination

curl -X POST https://api.wave.sa/v1/callback \
  -H "Authorization: Bearer sk_sandbox_xxxxxxxxxxxx" \
  -H "X-Wave-Simulate: server_error" \
  -H "Content-Type: application/json" \
  -d '{ "to": "+966500000000" }'

Limits

Sandbox keys are rate-limited — see Rate limits.

Get Started

Web Callback

Reference

Trial window

Destination lock

Test numbers & simulated errors

Limits

​Trial window

​Destination lock

​Test numbers & simulated errors

​Limits

Trial window

Destination lock

Test numbers & simulated errors

Limits