Skip to main content
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
NumberResult
+966500000017Simulated 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):
ValueSimulates
rate_limitRate-limit rejection
invalid_queueUnknown queue
queue_unavailableQueue temporarily unavailable
server_errorUpstream/telephony failure
invalid_numberInvalid 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.