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 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 E.164 destination.
See also
Last modified on June 12, 2026
