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 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 — 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 — 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
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 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 `+<country><area><number>` 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:<message-id>`) 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:<message-id>) also keeps a legitimate same-message retry from double-charging. Charged rows appear on your 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:

Tenant ID (dashboard → Settings → Organization; API → GET /api/v1/me returns it as organizationId)
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)
Destination number in E.164
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 (GET /api/v1/messages/:id/trace) first — the failure stage (validation / submission / carrier) narrows which class above to escalate.

Reference

Troubleshooting: fax sends fail or never arrive

Troubleshooting: fax sends fail or never arrive

Symptom map

Cause → fix

What not to do

Billing note

Escalation bundle

See also

​Troubleshooting: fax sends fail or never arrive

​Symptom map

​Cause → fix

​What not to do

​Billing note

​Escalation bundle

​See also

Troubleshooting: fax sends fail or never arrive

Symptom map

Cause → fix

What not to do

Billing note

Escalation bundle

See also