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

# Sandbox scenarios

> The canonical catalog of sandbox magic numbers and the outcomes they force.

Magic numbers are reserved destinations that force a specific outcome in sandbox environments. Use them in integration tests to deterministically exercise success, failure, and rejection paths without depending on carrier behavior.

The contract is enforced at two layers. Carrier-kind scenarios resolve through the sandbox carrier during the worker's poll loop and produce the same status transitions and webhook events a real carrier would. Rejection-kind scenarios are intercepted before the request reaches the controller, so no fax record is created, no credit hold is placed, and no webhook is dispatched.

| Number         | Scenario            | Kind      | Behavior                                                                                                               |
| -------------- | ------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------- |
| `+15005550001` | Delivered           | Carrier   | Succeeds on first attempt, 1 page                                                                                      |
| `+15005550002` | Busy                | Carrier   | Fails per attempt with `BUSY`; terminates failed after `max_attempts` retries exhausted                                |
| `+15005550003` | NoAnswer            | Carrier   | Fails per attempt with `NO_ANSWER`; terminates failed after `max_attempts` retries exhausted                           |
| `+15005550004` | DelayedDelivery     | Carrier   | Fails first attempt with a transient error, delivers on attempt 2+. Use to test retry-recovery code paths.             |
| `+15005550005` | LineQualityFailure  | Carrier   | Fails per attempt with `LINE_QUALITY`; terminates failed after `max_attempts` retries exhausted                        |
| `+15005550006` | InsufficientBalance | Rejection | Returns HTTP 402 with the `insufficient_balance` error envelope before submission. No fax record, no hold, no webhook. |
| `+15005550007` | DeliveredMultiPage  | Carrier   | Succeeds on first attempt, 3 pages. Use to verify per-page billing.                                                    |
| `+15005550008` | InvalidNumber       | Carrier   | Fails on attempt 1 with `INVALID_NUMBER`. Skips retries regardless of `max_attempts`.                                  |
| `+15005550099` | ValidationFailure   | Rejection | Returns HTTP 422 with a standard validator error envelope on the `to` field. No fax record.                            |

## Rejection-kind scenarios

`InsufficientBalance` and `ValidationFailure` reject the request before any fax row exists. `GET /v1/faxes/{id}` returns 404 for these requests because nothing was submitted. Your test should assert on the rejection response, not on a subsequent fax-state poll.

The response envelopes match what an organic rejection would produce, so the same error-handling code paths exercise both. See [Errors](/docs/errors) for the full envelope shape.

## Live environment behavior

Magic numbers behave specially **only** in sandbox environments. A live API key sending to any `+15005550XXX` number routes to the real carrier and is treated as an ordinary fax number.

## See also

* [Sandbox](/docs/sandbox) walkthrough.
* [Errors](/docs/errors) for the full error code catalog.
* [Idempotency](/docs/idempotency) for safe-retry semantics.