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.
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 fax number.
See also
Last modified on July 17, 2026
