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.

You have built and tested your integration in the sandbox. Before you swap your API key prefix from fx_test_ to fx_live_ and start sending real faxes, walk through this checklist. Each item takes a few minutes to verify and prevents the most common production issues.

​
The checklist

​
Error handling

Your code should parse the structured error envelope on every non-2xx response. Match on the error field (stable, machine-readable) rather than message (human-readable, may change).
  • You catch and log the error, message, and action fields
  • Validation errors (422) read context.errors for field-level detail
  • 402 insufficient_balance triggers an alert or automatic top-up flow, not a silent retry
  • 500 and 503 responses are retried; 400, 401, 402, and 422 are not
See the error catalog for every code and its recommended action.

​
Idempotency keys

Every POST /fax request should include an Idempotency-Key header. Without one, a network retry can create a duplicate fax.
  • You generate a unique key per logical fax operation (UUID v4 or a deterministic hash of recipient + document + your internal reference)
  • The same key is reused across retries of the same request
  • You understand that keys expire after 24 hours and are scoped per account
See Idempotency for key requirements and retry patterns.

​
Webhook endpoints

Webhooks are how you find out a fax was delivered, failed, or that your balance is running low.
  • At least one endpoint is registered via POST /account/webhooks
  • Your endpoint verifies the X-Mintfax-Signature header using HMAC-SHA256 and rejects requests with invalid or stale signatures
  • You deduplicate events using the event_id field (webhooks may be delivered more than once)
  • Your endpoint responds within 5 seconds to avoid triggering retries
  • You subscribe to fax.delivered, fax.failed, and balance.low at minimum
See Webhooks for event types and webhook signing for verification code in five languages.

​
Rate limit handling

mintfax enforces per-workspace rate limits. The response headers tell you where you stand.
  • You read the Retry-After header on 429 responses and wait before retrying
  • Batch or bulk-send workflows throttle requests rather than bursting
See Rate limits for header details and limit tiers.

​
Retry logic

Your client-side retry logic handles failures that happen before mintfax accepts the fax. Once mintfax returns 201, it owns delivery retries to the receiving machine.
  • You retry only on network errors, 500, and 503
  • Retries use exponential backoff with jitter (base 1s, max 30s, cap 5 attempts)
  • Every retry sends the same Idempotency-Key
See Idempotency - retry contract for which failures are yours and which are ours.

​
Balance monitoring

Live environments use real prepaid credits. A fax submission is rejected with 402 insufficient_balance if the available balance cannot cover the hold.
  • You subscribe to balance.low webhook events, or poll GET /account/balance on a schedule
  • You have an alert or automated process to top up before the balance hits zero
  • You understand the hold/capture/release lifecycle: credits are held on submission, captured on delivery, and released on failure
See Credits for the balance lifecycle and top-up options.

​
File validation

Validate files before sending them to avoid unnecessary 422 errors in production.
  • Files are one of the accepted types: PDF, DOCX, XLSX, JPG, PNG, TIFF, HTML, TXT
  • Files are under 10 MB
  • You handle the case where a user or upstream system provides an unsupported file type

​
Credential management

Live API keys grant access to real billing and real fax delivery.
  • Live keys (fx_live_) are stored in environment variables or a secrets manager, never in source control
  • Sandbox keys (fx_test_) are not used in production code paths
  • You have a process for rotating keys without downtime (generate new key, deploy, revoke old key)

​
Make the switch

The API base URL is the same for both environments. The key prefix determines routing, so switching to live is a credential change, not a URL change.
  1. Add a payment method in the dashboard to activate your live environment.
  2. Purchase credits for the live environment. Each live environment starts with a zero balance.
  3. Generate a live API key (fx_live_) from the dashboard.
  4. Deploy the new key to your production environment.
  5. Send a real fax to a known number you control and confirm delivery end to end: submission, webhook events, status polling, and balance deduction.
Sandbox test numbers (+1-555-XXX-XXXX) are rejected in the live environment. Make sure your test sends to a real E.164 number.

​
The first few days

After going live, keep an eye on a few things:
  • Delivery rates - real fax machines are slower and less predictable than sandbox simulations. Expect delivery times measured in seconds to minutes, not milliseconds.
  • Retry behavior - busy signals and temporary line errors trigger automatic retries (configurable 0-10 per fax). Monitor fax.failed events to catch permanent failures.
  • Balance consumption - credits are captured on delivery. If you send in bursts, watch the held amount via GET /account/balance to make sure your available balance stays above zero.
  • Webhook reliability - confirm your endpoint stays responsive under production load. Slow responses (over 5 seconds) trigger redelivery, which can compound if your endpoint is already backed up.
  • Retention settings - your data retention configuration carries over from sandbox. Verify it matches your production compliance requirements, especially if you handle HIPAA-regulated documents.

​
What to do next