> ## 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.

# fax.failed

> Sent when a fax has failed terminally.

## When it fires

Exactly once, when no further delivery attempt will be made. Two paths reach here:

1. **Retries exhausted.** Every retryable attempt up to `max_attempts` failed.
2. **Terminal error code returned.** A code classified as terminal (for example, `invalid_number`, `bad_destination`, `no_route`) was returned by an attempt. Remaining retries are skipped.

The credit hold is released and no charge is recorded.

## What your handler should do

* Branch on `error_code` to choose the next step. The codes are mintfax-owned and stable across carrier changes - they will not churn under you.
* `error_message` is human-readable English, suitable for showing in your dashboard. The agent-actionable contract is `error_code`.
* The full `attempts[]` array is included. Each entry carries its own `error_code` - useful when you want to see whether the failure was, say, three `busy` retries vs an immediate `invalid_number`.
* `fax.failed` and `fax.delivered` are mutually exclusive. The fax will not silently succeed after this event.

## Acting on common codes

| `error_code`      | What it means                                               | Typical action                                            |
| ----------------- | ----------------------------------------------------------- | --------------------------------------------------------- |
| `busy`            | Destination busy across every attempt.                      | Resubmit later or escalate to a human.                    |
| `no_answer`       | Destination did not answer within the carrier ring timeout. | Verify the number is monitored.                           |
| `line_quality`    | Connection negotiated but transmission failed.              | Resubmit; persistent failures point at the destination.   |
| `invalid_number`  | Destination is well-formed but not a fax line.              | Show it to the user; require correction.                  |
| `bad_destination` | Destination unreachable in a way retrying cannot help.      | Stop sending; investigate the routing record.             |
| `no_route`        | mintfax has no carrier route at the time of send.           | Retry later. The hold is already released.                |
| `timeout`         | Per-attempt timeout exceeded across attempts.               | Resubmit; investigate carrier-side outages if persistent. |
| `internal_error`  | mintfax-internal failure. Ops are alerted.                  | Resubmit. If persistent, contact support.                 |

See [Errors](/docs/errors) for the full code list including codes that return as 422 at submission time rather than as `fax.failed`.


## OpenAPI

````yaml openapi.json webhook fax.failed
openapi: 3.1.0
info:
  title: mintfax API
  version: '1.0'
  description: >-
    Developer-first fax API. Send faxes with a single API call.


    ## Authentication


    Most endpoints require a Bearer token in the `Authorization` header.


    - **Account keys** (`mfx_acct_...`) access account-level endpoints
    (`/account`, `/account/balance`, `/account/transactions`, `/account/keys`).

    - **Environment keys** (`mfx_test_...` for test, `mfx_live_...` for live)
    access operational endpoints (`/environment`, `/faxes`, `/webhooks`,
    `/events`).

    - Registration endpoints (`POST /account/register` and `POST
    /account/register/verify`) do not require authentication.


    ## Base URL


    All API requests use `https://api.mintfax.com/v1` as the base URL.
  contact:
    name: mintfax Support
    email: support@mintfax.com
    url: https://mintfax.com/docs
servers:
  - url: https://api.mintfax.com/v1
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Account
    description: >-
      Account-level resources: registration, account info, balances, and API
      keys.
  - name: Environment
    description: >-
      Test and live environment configuration shared across all operational
      requests.
  - name: Fax
    description: Send, list, retrieve, resend, and purge faxes.
  - name: Events
    description: >-
      Read the immutable event log for everything that has happened in the
      environment.
  - name: Webhooks
    description: >-
      Manage webhook endpoints and inspect or replay individual delivery
      attempts.
paths: {}
components:
  securitySchemes:
    bearerAuth:
      type: http
      description: |-
        API key as Bearer token. Use an account key (`mfx_acct_...`) for
        `/account/*` endpoints, and an environment key (`mfx_test_...` for
        sandbox, `mfx_live_...` for live) for `/environment/*`, `/faxes`,
        `/webhooks`, and `/events`.
      scheme: bearer

````