fax.failed

{
  "id": "evt_8aZqRm4yT3vK7pNxJ2bH9c",
  "type": "fax.failed",
  "created": 123,
  "data": {
    "object": {
      "id": "<string>",
      "to": "<string>",
      "pages": 123,
      "error_code": "<string>",
      "error_subcode": "<string>",
      "error_message": "<string>",
      "max_attempts": 3,
      "attempts": [
        {
          "attempt_number": 2,
          "started_at": "2023-11-07T05:31:56Z",
          "completed_at": "2023-11-07T05:31:56Z",
          "duration_ms": 123,
          "error_code": "<string>",
          "error_subcode": "<string>",
          "error_message": "<string>"
        }
      ],
      "webhook_url": "<string>",
      "idempotency_key": "<string>",
      "tags": {},
      "csid": "<string>",
      "submitted_at": "2023-11-07T05:31:56Z",
      "completed_at": "2023-11-07T05:31:56Z",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z"
    }
  }
}

WEBHOOK

fax.failed

{
  "id": "evt_8aZqRm4yT3vK7pNxJ2bH9c",
  "type": "fax.failed",
  "created": 123,
  "data": {
    "object": {
      "id": "<string>",
      "to": "<string>",
      "pages": 123,
      "error_code": "<string>",
      "error_subcode": "<string>",
      "error_message": "<string>",
      "max_attempts": 3,
      "attempts": [
        {
          "attempt_number": 2,
          "started_at": "2023-11-07T05:31:56Z",
          "completed_at": "2023-11-07T05:31:56Z",
          "duration_ms": 123,
          "error_code": "<string>",
          "error_subcode": "<string>",
          "error_message": "<string>"
        }
      ],
      "webhook_url": "<string>",
      "idempotency_key": "<string>",
      "tags": {},
      "csid": "<string>",
      "submitted_at": "2023-11-07T05:31:56Z",
      "completed_at": "2023-11-07T05:31:56Z",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z"
    }
  }
}

When it fires

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

Retries exhausted. Every retryable attempt up to max_attempts failed.
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 for the full code list including codes that return as 422 at submission time rather than as fax.failed.

Authorizations

Authorization

string

header

required

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.

Body

application/json

Event delivery to your subscribed webhook endpoint.

Webhook delivery for fax.failed.

string

required

Event identifier (evt_-prefixed). Stable across retry attempts.

Example:

"evt_8aZqRm4yT3vK7pNxJ2bH9c"

type

enum<string>

required

Event type. Always fax.failed for this delivery.

Available options:

fax.failed

created

integer

required

Unix epoch seconds when the event was generated.

data

object

required

Show child attributes

Response

2XX

Acknowledged. mintfax treats any 2xx response as a successful delivery.

Last modified on July 20, 2026

fax.delivered balance.low

Get Started

Event types

When it fires

What your handler should do

Acting on common codes

Authorizations

Body

Response

​When it fires

​What your handler should do

​Acting on common codes

Authorizations

Body

Response

When it fires

What your handler should do

Acting on common codes