Skip to main content

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.

​
Symptom

Your API request returned an error, a webhook never arrived, or a fax failed after submission. This page maps each symptom to its cause and fix.

​
Root cause taxonomy

  • Send failures - the fax could not be delivered (busy line, no answer, invalid number)
  • Balance failures - the workspace does not have enough credits
  • Authentication and authorization failures - the API key is missing, invalid, or belongs to an inactive workspace
  • Webhook delivery failures - mintfax sent an event but your endpoint did not receive it
  • Signature verification failures - your code rejected a valid webhook payload
  • File format issues - the uploaded document could not be processed
  • Idempotency key collisions - a reused key returned a cached response you did not expect

​
Decision flow

  1. Check the HTTP status code. If 4xx, the request was rejected before any fax attempt. See the diagnostics matrix below.
  2. If 201, the fax was accepted. Poll the fax status via GET /v1/faxes/{id}. A failed status with an error_code field means a send failure.
  3. Expected a webhook that did not arrive? See Webhook delivery failures.
  4. Webhook arrived but signature verification failed? See Signature verification failures.

​
Diagnostics matrix

Error code from the API response body, HTTP status, cause, and fix.
Error codeHTTPCauseFix
validation_failed422A required field is missing or malformed (e.g. to is not valid E.164, or no file attached)Check the errors object in the response for the failing field. Correct and retry.
insufficient_balance402Workspace balance is too low to cover the fax costTop up credits via the dashboard or billing API, then retry. See error catalog.
unauthenticated401No valid bearer token providedAdd Authorization: Bearer <your-api-key> to the request header.
api_key_missing401The Authorization header is absentInclude the header with your sandbox or live API key.
api_key_invalid401The API key does not match any active keyVerify the key in the dashboard. Sandbox keys start with fx_test_, live keys with fx_live_.
workspace_inactive403The API key belongs to a deactivated workspaceReactivate the workspace in the dashboard or contact support.
forbidden403The authenticated key lacks access to this resourceConfirm you are using the correct workspace’s API key.
not_found404The fax ID or resource does not exist in this workspaceVerify the ID. Resources are scoped to the workspace that created them.
fax_not_terminal409You tried to delete or resend a fax still in progressWait until the fax reaches delivered or failed, then retry.
fax_data_purged422The fax document has been purged per retention policySubmit a new fax with the original document. Purged data cannot be recovered.
rate_limit_exceeded429Too many requests in a short windowBack off and retry after the Retry-After header value.
internal_server_error500Unexpected error on the mintfax sideRetry with an idempotency key. If it persists, contact support with the request ID.
Full descriptions of every code are in the error catalog.

​
Send failures

These show up as a failed fax status with an error_code on the fax object. The fax was accepted (HTTP 201), but the carrier could not deliver it. Busy line. The receiving machine was occupied. mintfax retries automatically up to the configured limit. Once retries are exhausted, the fax fails. Resend manually via POST /v1/faxes/{id}/resend after the fax reaches a terminal state. Simulate with sandbox magic number +15005550002. No answer. The receiving number rang without pickup, typically because it is a voice line or the machine is off. Confirm the number with the recipient. Simulate with +15005550003 in the sandbox. Permanent failure. The carrier reported an unrecoverable error (e.g. disconnected number). Verify the receiving number before resending. Simulate with +15005550005.

​
Webhook delivery failures

If your endpoint did not receive an expected event, work through these checks in order:
  1. Confirm the URL registered via POST /v1/webhook-endpoints is correct and publicly reachable.
  2. mintfax treats any non-2xx response as a failure and retries with exponential backoff. Check your server logs for 4xx or 5xx responses.
  3. Verify your firewall allows inbound HTTPS from mintfax’s IP ranges.
  4. If you configured the endpoint for specific event types only, confirm the event you expect is in the filter list.
  5. Check recent deliveries in the dashboard. The webhook log shows the response code mintfax received from your endpoint.
When deliveries fail repeatedly, mintfax disables the endpoint. Re-enable it in the dashboard after you fix the underlying problem.

​
Signature verification failures

Every webhook delivery includes a signature header. If your verification code rejects valid payloads, check these:
  1. Wrong signing secret. Each webhook endpoint has its own secret. Verify with the secret for the endpoint that received the delivery.
  2. Stale secret after rotation. Both old and new secrets are valid during a brief overlap window. Check both during rotation.
  3. Body mutation. The signature covers the raw request body. If a proxy, load balancer, or framework re-serializes the JSON before your handler runs, the signature will not match. Verify against the raw bytes.
  4. Clock skew. Replay protection rejects payloads older than five minutes. Synchronize your server clock via NTP.
See the events schema for the webhook payload structure and the glossary for related terms.

​
File format issues

A validation_failed error (HTTP 422) when the uploaded document cannot be processed. Common causes:
  • The file type is not supported. mintfax accepts PDF, TIFF, and common image formats.
  • The file is corrupt or unreadable. Re-export or re-scan the document and retry.
  • The file exceeds the 10 MB upload limit. Split large documents into smaller batches.
The errors object in the response body names the specific field and reason.

​
Idempotency key collisions

Reusing an Idempotency-Key header value with a different request body does not send a new fax. mintfax returns the cached response from the original request.
  • Same key, same body: mintfax returns the stored response. Safe to retry.
  • Same key, different body: mintfax returns the stored response from the first request. The second body is ignored. Generate a new key for each distinct request.
Keys expire after 24 hours. After expiration, the key can be reused with a new body. See idempotency for details.

​
Escalation

Contact support if:
  • internal_server_error persists across multiple retries with different idempotency keys
  • Webhook deliveries keep failing after you have verified the endpoint URL and network configuration
  • A fax is stuck in in_progress for more than 15 minutes
Include the request_id from the response headers and the fax ID when you write in.