> ## Documentation Index > Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt > Use this file to discover all available pages before exploring further. # Troubleshooting: fax sends fail or never arrive > Read a failed fax end to end — send-time 4xx content/destination rejects, carrier passthrough failures (busy, no answer, no fax tone, poor line quality), transient gateway 5xx, and the on-success billing rule. Cause table, retry discipline, and the escalation bundle. # Troubleshooting: fax sends fail or never arrive Fax failures split into four classes, and the fix is different for each: the API refused the send (content/destination reject), the carrier failed the transmission (passthrough failure with a diagnostic), a transient gateway error sits between your client and the carrier, or the record terminal'd `sent` but the recipient never received pages. This page walks all four, with the billing rule that decides what each one costs you. If the row is stuck pre-queue (`queued`, `pending`), work the [queue-side troubleshooting page](/reference/troubleshooting) instead. This page assumes the send was dispatched. ## Symptom map Three surfaces read the same fax row: the Delivery Log filtered by channel (`/messages/delivery-log?channel=fax`), the authoritative row on `GET /api/v1/messages/:id`, and the `message.failed` webhook payload with `channel: "fax"`. Match the symptom to its class first — the same status word points at different layers. | Symptom | Failure class | Where to confirm | | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | **422 `INVALID_PHONE_NUMBER` / `MISSING_REQUIRED_FIELD` / `VALIDATION_ERROR` at POST time** | Destination or payload reject — the request never left validation | The [Fax channel errors table](/channels/fax#errors) — field-level detail in `error.details` | | **Non-PDF/TIFF `media_url`, or `http://` URL rejected at send time** | Content reject — document type or scheme the carrier cannot transmit | Request `media_url`; the [Fax limits](/channels/fax#limits) — PDF or TIFF only, 50 MB max, HTTPS only | | **502 `MESSAGE_SEND_FAILED`** | Gateway/provider reject at dispatch — account state or connection misconfiguration | `details.provider_message` in the error envelope; your [per-tenant Telnyx Fax connection](/channels/fax#capabilities) | | **Row `failed`, webhook carries `busy` / `no_answer` / `no fax tone`** | Destination reject — the line was occupied or no fax device answered | `message.failed` payload `error_code` / `error_message` — carrier's own wording | | **Row `failed`, webhook carries `poor_line_quality` or `handshake_rejected`** | Line-quality reject — the T.38 handshake could not hold | Same `error_code` / `error_message` fields; higher when `quality: very_high` on lossy destinations | | **Row `sent`, never received at the recipient** | Carrier-completed but end station never ack'd — `sent` is non-terminal | Poll `GET /api/v1/fax/:id/status` until `delivered` or `failed`; the [status lifecycle](/channels/fax#status-lifecycle) explains the split | | **429 on the send endpoint** | Rate gate, not a fax failure — the row never formed | `retry_after` in the error envelope; fax shares the unified messaging send surface | ## Cause → fix Work the class you matched above. Each fix is a one-shot check before you resend — fax is single-attempt from the queue side (the worker only re-dispatches while the row is `queued`), so a terminal `failed` row is re-sent as a **new** message. | Cause class | Fix | | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Destination format reject (422) | Verify E.164 `+` before re-sending. A bare 422 `VALIDATION_ERROR` on `status_callback_secret` or `status_callback_events` means you paired one callback field without the URL — check `error.details.field`. | | Content reject (non-PDF/TIFF, over 50 MB, `http://` URL) | Convert the document to PDF or TIFF server-side before submitting, and host it on an HTTPS URL. The carrier fetches the URL at send time — an `http://` URL is refused up front. | | Gateway 5xx (`MESSAGE_SEND_FAILED`) | Retry the POST once — the envelope carries `retry_after` when one applies, and the provider-side idempotency key (`orbit-fax:`) dedups a legitimate retry so you never double-bill. A persistent 5xx means the provider connection is misconfigured, not transient: check your tenant `fax_connection_id` and the provider's account state before a second attempt. | | Destination noise (`busy` / `no_answer`) | The destination line was occupied or never picked up. Confirm the number with the recipient, then resend during the destination's business hours — the same deterministic answer comes back until someone clears the line. | | Line-reachability noise (`no fax tone`) | The number answered but presented no fax handshake — usually a voice line misrouted, or a recipient expecting manual receive. Verify the number is actually a fax endpoint before another send. | | Line quality (`poor_line_quality` / `handshake_rejected`) | Lower the `quality` parameter — `very_high` lengthens the T.38 handshake and tips a lossy line into failure; `high` or `normal` shortens it. Resend at a lower quality or a different hour. | | Delivered-to-carrier but never received (`sent`, no `delivered`) | `sent` is non-terminal and `delivered` is non-guaranteed on fax. Poll `GET /api/v1/fax/:id/status` (cached \~10 seconds) until the row resolves; a long hold at `sent` ends in `failed` or `delivered`, and only `delivered` confirms the end station ack'd. | | 429 rate gate on the send | Fax shares the unified messaging send surface — there is no separate fax bucket. Honour `retry_after` in the envelope and send after the cooldown; the row never formed, so nothing to re-send. | ## What not to do * **Do not retry a destination reject (`busy`, `no answer`, `no fax tone`) in a loop.** These are deterministic — the same send fails the same way until the line frees or the recipient confirms the number. One sensible re-send after the line clears, not a retry loop. * **Do not resend the same payload against `poor_line_quality` without lowering `quality`.** The handshake length is the variable; unchanged, the re-send fails the same way. * **Do not count a `sent`-hold as delivered.** Carriers ack `delivered` at different points; treat `sent` as carrier-completed and only `delivered` as end-station-confirmed. * **Do not bypass `retry_after` on a 5xx.** A single retry is the shape defined here; repeated immediate retries against a provider 5xx amplify the queue rather than recover it. ## Billing note Fax is **on-success-charge** — your wallet deducts only when the carrier confirms a successful transmission. Every failure class above (content reject, destination reject, gateway 5xx, line failure, delivered-never-received) is **not billed** — this holds for both the initial send and any sensible re-send. The provider-side idempotency key (`orbit-fax:`) also keeps a legitimate same-message retry from double-charging. Charged rows appear on your [billing overview](/billing/overview) only after a successful transmission. ## Escalation bundle Open a support ticket when one of these holds: * A 502 `MESSAGE_SEND_FAILED` persists after one retry and your tenant `fax_connection_id` resolves cleanly. * A destination reports fax-reachable and the carrier returns `handshake_rejected` on every attempt. * A row held at `sent` for several hours with no `delivered` or `failed` terminal. Include the four fields support needs to pull the provider trace without a back-and-forth: 1. **Tenant ID** (dashboard → Settings → Organization; API → `GET /api/v1/me` returns it as `organizationId`) 2. **Re-enquire `request_id`** — the send POST's `meta.request_id` (returned in the error envelope for the 4xx/5xx classes, or in the successful enqueue response for the terminal `failed` class) 3. **Destination number** in E.164 4. **Fax/Message ID** — `msg_…` from the row (On route `GET /api/v1/fax/:id`, the provider-side `external_id` attaches after dispatch — include both where present) For a held-at-`sent` row, run the self-serve [route-trace timeline](/concepts/message-route-trace) (`GET /api/v1/messages/:id/trace`) first — the failure stage (`validation` / `submission` / `carrier`) narrows which class above to escalate. ## See also * [Fax channel page](/channels/fax) — send fields, errors, limits, and the status lifecycle this page decodes * [Outbound fax workflow](/guides/fax-send-workflow) — the complete send-side walkthrough: billing timing, receipts, and document guidance * [Delivery log](/guides/delivery-log) — the dashboard surface behind the `channel=fax` filter * [Message undelivered or failed](/troubleshooting/message-undelivered-failed) — the channel-agnostic failure decoder (the classifier `metadata.classified_error_code`) * [Error codes](/reference/error-codes) — the JSON error envelope and the `MESSAGE_SEND_FAILED` / validation code catalog * [Webhook events](/webhooks/events) — the `message.delivered` / `message.failed` payloads (`channel: "fax"` events arrive on the channel-agnostic surface)