Go live with confidence

You have built and tested your integration in the sandbox. Before you swap your API key prefix from mfx_test_ to mfx_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 /webhooks
• Your endpoint verifies the webhook-signature header (Standard Webhooks format) and rejects requests with invalid or stale signatures
• You deduplicate events using the webhook-id header (webhooks may be delivered more than once)
• Your endpoint responds within 30 seconds to avoid triggering retries
• You subscribe to fax.delivered, fax.failed, and balance.low at minimum

See Webhooks for event types and Verify webhook signatures for verification code in five languages.

​

Rate limit handling

mintfax enforces per-environment 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 (mfx_live_) are stored in environment variables or a secrets manager, never in source control
• Sandbox keys (mfx_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 (mfx_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 numbers (+1-555-XXX-XXXX) are rejected in the live environment. Make sure your sandbox 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

• Live environment - prerequisites and differences from sandbox
• Error catalog - every error code and what to do about it
• Idempotency - retry safely without duplicate faxes
• Rate limits - request limits and Retry-After headers
• Webhooks - event types, payload format, and delivery behavior