Understand error codes and what to do about them

Error codes, HTTP statuses, causes, and recommended actions

Every mintfax API error returns a consistent JSON envelope. The error field is a stable, machine-readable code you can match on. The message field is human-readable. Most errors also include action (a programmatic hint for what to do next) and docs (a permalink back to this page).

Every error envelope also includes a request_id field matching the X-Request-Id response header. Include it when contacting support or filing a ticket. See Request IDs.

Error response shape

{
  "error": "insufficient_balance",
  "message": "Insufficient balance for this operation.",
  "action": "top_up_balance",
  "docs": "https://mintfax.com/docs/errors/insufficient-balance",
  "request_id": "req_01J9XYZQ8KH7B3R0WXAZP8VW6F"
}

Field	Type	Always present	Description
error	string	Yes	Stable machine-readable code from the catalog below
message	string	Yes	Human-readable description
action	string	Yes	Programmatic next step (see per-code entries)
docs	string	Yes	Permalink to the relevant entry on this page
request_id	string	Yes	The req_* ID for this request - quote it in support tickets
context	object	No	Extra fields specific to the error (e.g. validation details, balance amounts)

Validation errors include a nested context.errors object with field-level messages. See validation_failed below.

---

Error catalog

Each entry below is a stable error code returned in the error field. Anchors on this page match the code with hyphens (e.g. /errors#insufficient-balance).

validation_failed

HTTP	Action
422	fix_request

The request body or query parameters failed validation. Check context.errors for per-field messages.

When it fires: A required field is missing, a field has the wrong type, or a value is outside its allowed range.

What caused it: The request payload does not satisfy the endpoint’s validation rules. Common triggers: omitting to or file on POST /fax, sending a non-E.164 phone number, or exceeding the 10 MB file size limit.

Next step: Read context.errors, fix the flagged fields, and resubmit. The response body looks like this:

{
  "error": "validation_failed",
  "message": "The to field is required.",
  "action": "fix_request",
  "docs": "https://mintfax.com/docs/errors/validation-failed",
  "context": {
    "errors": {
      "to": ["The to field is required."],
      "file": ["The file must be a PDF, TIFF, or JPEG."]
    }
  }
}

---

unauthenticated

HTTP	Action
401	check_credentials

No valid credentials were provided.

When it fires: The Authorization header is present but the value is not a recognized Bearer format, or the header contains a malformed value.

What caused it: The request included an Authorization header that could not be parsed as a Bearer API key.

Next step: Confirm the header value is Bearer mfx_test_... (sandbox) or Bearer mfx_live_... (live). Regenerate the API key in the dashboard if needed.

---

api_key_missing

HTTP	Action
401	check_credentials

No Authorization header was sent.

When it fires: The request reaches the API gateway without an Authorization header.

What caused it: The HTTP client is not attaching the header. This is common when switching between sandbox and production base URLs and forgetting to set the header in the new environment.

Next step: Add Authorization: Bearer <your-api-key> to the request.

---

api_key_invalid

HTTP	Action
401	check_credentials

The API key was sent but is not recognized.

When it fires: The presented API key does not match any key on file.

What caused it: The API key was revoked, rotated, or copied incorrectly. Trailing whitespace and newline characters are common culprits when keys are pasted from a .env file.

Next step: Verify the API key in your dashboard. If it was rotated, use the new one. If you are unsure which environment you are targeting, sandbox keys start with mfx_test_ and live keys start with mfx_live_.

---

forbidden

HTTP	Action
403	check_credentials

The API key is valid but does not have permission to access this resource.

When it fires: The authenticated environment does not own the requested resource (e.g. fetching a fax that belongs to a different environment).

What caused it: A fax ID or resource ID from one environment was used with an API key from another environment.

Next step: Confirm you are using the correct API key for the environment that owns the resource. If you manage multiple environments, check that the fax ID matches the environment you are calling.

---

key_not_scoped_for_account

HTTP	Action
403	use_account_key

An environment key was used on an account-level route.

When it fires: A mfx_test_... or mfx_live_... key hits an account-management endpoint such as /account/balance, /account/transactions, or /account/keys.

What caused it: Environment keys (sandbox or live) are operational keys. They can send and read faxes inside an environment but cannot read or manage account-level resources. Account-level reads require an mfx_acct_... key.

Next step: Switch to your account-scoped key. The first acct key was returned at registration alongside the sandbox key; additional acct keys are created from the dashboard. See Keys for the full scope matrix.

---

key_not_scoped_for_operations

HTTP	Action
403	use_operational_key

An account key was used on an operational route.

When it fires: A mfx_acct_... key hits an operational endpoint such as POST /faxes, GET /faxes/{id}, or GET /environment/*.

What caused it: Account keys are admin keys for managing the account, not for sending or reading faxes. They cannot reach the operational surface.

Next step: Use a mfx_test_... (sandbox) or mfx_live_... (live) key for operational routes. See Keys for which key kind belongs on which endpoint.

---

acct_key_creation_dashboard_only

HTTP	Action
403	use_dashboard

Account-scoped keys cannot be created or deleted via the API.

When it fires: POST /account/keys with scope_kind=account, or DELETE /account/keys/{id} against an existing account-scoped key.

What caused it: Account-scoped keys are admin-equivalent for the entire account. Their lifecycle is intentionally restricted to the dashboard (a human-loop attestation step) so an API-only chain of compromise cannot escalate from a stolen environment key to full account control.

Next step: Create or revoke mfx_acct_... keys from the dashboard. Environment keys (mfx_test_... and mfx_live_...) can still be created and deleted via the API with an account key. See Keys - Account keys.

---

account_not_activated

HTTP	Action
403	activate_account

The account has not completed the buy-as-activation flow, so live operations are blocked.

When it fires: A mfx_live_... key hits an operational route (POST /faxes, GET /environment/*, etc.) on an account whose activated_at timestamp is null.

What caused it: Live access requires a first successful credit purchase. The account exists, the key authenticates, but activation has not happened yet. See Activation for the full flow and the reasoning behind tying activation to a real purchase rather than just a saved card.

Next step: Log in to the dashboard, click Activate Live, and complete the Stripe Checkout that captures the card and funds the first credit package. Activation is atomic with that purchase. Sandbox routes continue to work in the meantime.

---

not_found

HTTP	Action
404	verify_id

The requested resource does not exist.

When it fires: A GET, DELETE, or POST .../resend targets a fax ID (or other resource ID) that does not exist in the current environment.

What caused it: The ID is wrong, the resource was deleted, or you are querying the sandbox environment for a fax that was sent in the live environment (or vice versa).

Next step: Double-check the resource ID. Confirm you are using the right API key for the right environment. If the fax was deleted via DELETE /fax/{id}, it is gone permanently.

---

insufficient_balance

HTTP	Action
402	top_up_balance

Not enough credits to complete this operation.

When it fires: POST /fax or POST /fax/{id}/resend is called and the environment’s available balance (current balance minus outstanding holds) is less than the cost of the fax.

What caused it: The environment has run out of credits or has too many in-flight faxes holding credits. In the sandbox environment, the sandbox starts with a fixed credit balance that can be reset from the dashboard.

Next step: Purchase more credits in the dashboard or wait for in-flight faxes to complete (which releases their holds). Check GET /account/balance to see your current available balance.

---

fax_data_purged

HTTP	Action
422	submit_new_fax

The fax document data has been deleted and cannot be retrieved or resent.

When it fires: GET /fax/{id}/image or POST /fax/{id}/resend is called for a fax whose document data has been purged from storage.

What caused it: The fax reached a terminal state and the data retention window expired. If the environment uses zero-footprint mode, document data is deleted immediately after the fax reaches a terminal state.

Next step: Submit a new fax with the original document. The fax metadata record (GET /fax/{id}) is still available even after the document data is purged.

---

fax_not_terminal

HTTP	Action
409	wait_for_completion

The fax has not yet reached a terminal state.

When it fires: DELETE /fax/{id} is called while the fax status is queued, submitted, or in_progress.

What caused it: You attempted to delete a fax that is still being processed. A fax must reach delivered or failed status before it can be deleted.

Next step: Poll GET /fax/{id} or listen for the terminal event via your webhook, then retry the delete. See the glossary for definitions of fax statuses.

---

rate_limit_exceeded

HTTP	Action
429	wait_and_retry

Too many requests in too short a window.

When it fires: The request rate for this API key exceeds the allowed threshold at the API gateway.

What caused it: Bursting too many requests. Automated retry loops without backoff are a common trigger.

Next step: Back off and retry with exponential delay. The Retry-After header (when present) tells you how many seconds to wait. If you consistently hit the limit, contact support to discuss a rate increase.

---

internal_server_error

HTTP	Action
500	retry_or_contact_support

Something unexpected went wrong on the mintfax side.

When it fires: An unhandled exception or infrastructure failure occurs while processing the request.

What caused it: A bug or transient failure in the mintfax backend. Your request was valid.

Next step: Retry the request. If you included an Idempotency-Key header, the retry is safe to repeat without side effects. If the error persists, contact support with the request ID from the response headers.

---

HTTP status code summary

Code	Meaning
200	Success
201	Resource created
204	Success, no content
400	Bad request (malformed JSON, wrong content type)
401	Missing or invalid API key
402	Insufficient balance
403	Forbidden, environment inactive, account not activated, or key scoped wrong
404	Resource not found
409	Conflict (resource not in expected state)
422	Validation error, or fax data purged
429	Rate limit exceeded
500	Internal server error

---

Related pages

• Events - webhook event types and payloads
• Glossary - definitions of fax statuses, environments, and other terms

Last updated: 2026-05-11