{
"id": "evt_8aZqRm4yT3vK7pNxJ2bH9c",
"type": "fax.failed",
"created": 123,
"data": {
"object": {
"id": "fax_8aZqRm4yT3vK7pNxJ2bH9c",
"status": "queued",
"to": "+12125551234",
"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"
}
}
}Event types
fax.failed
Sent when a fax has failed terminally.
WEBHOOK
fax.failed
{
"id": "evt_8aZqRm4yT3vK7pNxJ2bH9c",
"type": "fax.failed",
"created": 123,
"data": {
"object": {
"id": "fax_8aZqRm4yT3vK7pNxJ2bH9c",
"status": "queued",
"to": "+12125551234",
"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_attemptsfailed. - 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.
What your handler should do
- Branch on
error_codeto choose the next step. The codes are mintfax-owned and stable across carrier changes - they will not churn under you. error_messageis human-readable English, suitable for showing in your dashboard. The agent-actionable contract iserror_code.- The full
attempts[]array is included. Each entry carries its ownerror_code- useful when you want to see whether the failure was, say, threebusyretries vs an immediateinvalid_number. fax.failedandfax.deliveredare 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. |
fax.failed.Authorizations
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.
Event identifier (evt_-prefixed). Stable across retry attempts.
Example:
"evt_8aZqRm4yT3vK7pNxJ2bH9c"
Event type. Always fax.failed for this delivery.
Available options:
fax.failed Unix epoch seconds when the event was generated.
Show child attributes
Show child attributes
Response
2XX
Acknowledged. mintfax treats any 2xx response as a successful delivery.
Last modified on July 20, 2026