> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wave.sa/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandbox mode

> What sandbox keys can do: the trial window, destination lock, test numbers, and the simulate header.

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           |

```bash theme={null}
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](/rate-limits).