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.
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).
Error response shape
{
"error": "insufficient_balance",
"message": "Insufficient balance for this operation.",
"action": "top_up_balance",
"docs": "https://mintfax.com/docs/errors/insufficient-balance"
}
| 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 |
context | object | No | Extra fields specific to the error (e.g. validation details, balance amounts) |
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
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 |
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 fx_test_... (sandbox) or Bearer fx_live_... (live). Regenerate the API key in the dashboard if needed.
api_key_missing
| HTTP | Action |
|---|
| 401 | check_credentials |
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 |
.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 fx_test_ and live keys start with fx_live_.
forbidden
| HTTP | Action |
|---|
| 403 | check_credentials |
not_found
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 |
POST /fax or POST /fax/{id}/resend is called and the workspace’s available balance (current balance minus outstanding holds) is less than the cost of the fax.
What caused it: The workspace 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 |
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 workspace 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 |
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.
workspace_inactive
| HTTP | Action |
|---|
| 403 | activate_workspace |
rate_limit_exceeded
| HTTP | Action |
|---|
| 429 | wait_and_retry |
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 |
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, or workspace inactive |
| 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-09
