Skip to main content
WEBHOOK
fax.failed
{
  "id": "evt_8aZqRm4yT3vK7pNxJ2bH9c",
  "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"
    }
  }
}

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.

​
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 surfacing 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_codeWhat it meansTypical action
busyDestination busy across every attempt.Resubmit later or escalate to a human.
no_answerDestination did not answer within the carrier ring timeout.Verify the number is monitored.
line_qualityConnection negotiated but transmission failed.Resubmit; persistent failures point at the destination.
invalid_numberDestination is well-formed but not a fax line.Surface to the user; require correction.
bad_destinationDestination unreachable in a way retrying cannot help.Stop sending; investigate the routing record.
no_routemintfax has no carrier route at the time of send.Retry later. The hold is already released.
timeoutPer-attempt timeout exceeded across attempts.Resubmit; investigate carrier-side outages if persistent.
internal_errormintfax-internal failure. Ops are alerted.Resubmit. If persistent, contact support.
See Errors for the full code list including codes that surface 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.

​
id
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

Response

2XX

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

Last modified on May 14, 2026