Errors and job states
Updated
Every non-2xx answer is one envelope. The code says what happened. retryable is true when the failure passes on its own: send the same call again, unchanged, after a short wait. It is false when the same call gets the same answer until something changes, in your request or in the resource. correlation_id is what to quote when you write to us.
{"error": {"code": "insufficient_balance", "message": "the wallet holds $0.80 and the quote is $1.17", "retryable": false, "correlation_id": "9f2c41d07b3a5e68"}} A receipt asked for before its fax has ended is the case to know. It answers 409 conflict with retryable: false, because asking again at once gets the same 409. Wait for the fax to end, by its webhook or GET /v1/faxes/{id}, then ask again.
The reference and the OpenAPI document list the statuses each operation can answer. A call with no valid API key gets 401. A call without the scope gets 403, and one past the rate limit gets 429. Branch on code, not on the status alone.
Terminal provider refusals use a specific 4xx code or the resource's failed state. Customer routes never return 502 or 504. Cloudflare can replace origin 502, 503 and 504 responses with an HTML error page. We reserve 503 for service outages, missing provider configuration and maintenance. The origin sends JSON for these outages, but clients must handle an HTML response from the edge.
A refused number purchase returns 201 with status: failed, the carrier's reason in error, and its hold released. Repeat the request with its original Idempotency-Key to get the same body. See number orders.
Codes
| Code | Status | What to do |
|---|---|---|
invalid_token | 401 | the key is missing, revoked or malformed. Get a key from the dashboard |
scope_missing | 403 | the API key lacks the scope. The message names it |
agent_forbidden | 403 | an agent key is not allowed on this route. A person does this |
not_found | 404 | no such resource in your organization. A foreign id and a deleted one look the same. When a call carries two ids, details.field names the one that was not found |
invalid_request | 400 or 422 | the body failed validation. details lists the fields |
conflict | 409 | the resource is in a state that forbids the call. Read it again before you retry. A receipt asked for before the fax has ended is this code, with the state in details.state. Read the job until it has ended, then ask again |
idempotency_key_conflict | 409 | this Idempotency-Key was used with a different body. details.resource_id names the first resource. Use a new key for a new request |
not_cancelable | 409 | the fax has already ended. details.state names its state |
document_expired, inbox_item_expired | 410 | the document or received fax passed its retention date and is no longer kept. Once the hourly cleanup has removed it, the id answers 404 not_found, like one you deleted |
organization_deleted | 410 | the organization is being deleted. Its keys no longer work |
account_suspended | 403 | sending is suspended for this account. Write to us |
encrypted_pdf, unsupported_format, page_limit_exceeded | 422 | fix the document and create it again. Nothing was stored or charged |
unsupported_characters | 422 | text, a sender name or a cover field has a character the page fonts cannot print. details names the field and the code point. Remove it, or send the document as a PDF. Nothing was stored or charged |
conversion_failed, image_too_large | 422 | the HTML took longer than 45 seconds to render, or an image frame is over 50 million pixels. Make it smaller and create it again |
render_unavailable | 503 | the HTML renderer is down. Retryable |
live_provider_unavailable | 503 | live sending is not enabled on this server yet, so live quotes, sends and number orders are refused. Test keys keep working. Not retryable |
unsupported_destination | 422 | no published route, excluded by policy, or a kind of number outside the United States and Canada that the landline price does not cover. Not retryable |
dispute_open | 403 | live sends from the wallet are paused while a card dispute on the account is open. They resume when it is closed. Test keys keep working |
invalid_destination | 422 | the number is not a valid E.164 number. Correct it |
sender_not_owned | 422 | POST /v1/sender-verifications names a number that is not one of yours. A quote with such a from answers 404 not_found, with details.field set to from. Omit from to send from the shared pool |
quote_consumed | 409 | this quote already created a fax. details names it. Read that fax |
document_hash_mismatch | 409 | the document changed or was deleted after the quote. Quote again |
quote_expired | 409 | quote again. Quotes last ten minutes |
insufficient_balance | 402 | top up the wallet. The provider was not called |
budget_exceeded, agent_budget_exceeded | 403 | the cap for the period is reached. A person raises it or waits |
approval_required | 403 | a live send with no approval and no allowing policy. Ask a person |
approval_* | 409 | see the approvals page. Quote and ask again |
sandbox_only, environment_not_billable | 403 | the route is for the other kind of key. |
payload_too_large | 413 | the request body is over the limit of its route. A JSON call takes 1 MiB. POST /v1/documents and a call to the MCP server take 4 MiB, which holds an HTML document of 2 MiB. The MCP server names the error request_too_large. The bytes of an upload take 25 MiB. Send a smaller body. The limits page lists every limit with its value |
rate_limited | 429 | 600 requests a minute per key, 3,000 while the Agent workspace plan is active. Retryable after RateLimit-Reset |
workspace_required | 403 | the records export comes with the Agent workspace plan, and stays open 30 days after it ends. Start the plan on the dashboard's Billing page |
inventory_rejected, number_release_rejected, portability_rejected, port_order_rejected | 409 or 422 | the carrier refused the request. Read its reason in message. Correct the request before trying again |
number_not_ready | 409 | the carrier has not finished setting up the number. Wait before requesting its release |
number_taken, number_quarantined | 409 | the number is on an account, or was released in the last 30 days. Choose another number |
number_in_use | 409 | a fax from this number is still in flight. Wait for it to end before releasing the number |
agent_disabled | 409 | the agent is disabled. A person enables it before a key is made for it |
billing_request_rejected | 422 | the payment provider refused the request. Read message and correct the request |
payment_declined | 402 | the payment was refused. Read message and use another payment method |
billing_conflict | 409 | the payment provider found a conflicting request. Check the existing payment before trying again |
oauth_exchange_failed, oauth_identity_incomplete | 422 | start a new sign-in or use an email link |
ocr_disabled | 409 | live extraction is disabled. Repeating the request cannot enable it |
document_not_rendered | 409 | the document has no page images to read. Create it again |
billing_unavailable, temporarily_unavailable, provider_timeout, provider_unavailable, oauth_unavailable | 503 | retry after the service recovers. Reuse the same Idempotency-Key for a mutation |
internal_error | 500 | retryable. Quote the correlation id if it persists |
Every code
This list is read from the server's source at each release, so it has every code the envelope can carry: 132 of them. The last column says where a code is met. With an API key you meet the codes of the API routes. The dashboard, the affiliate program and the one-time send have codes of their own.
| Code | Status | Where |
|---|---|---|
account_not_in_good_standing | 403 | affiliate program |
account_suspended | 403 | faxes, one-time send |
affiliate_ended | 409 | affiliate program |
affiliate_not_active | 403 | affiliate program |
affiliate_suspended | 409 | affiliate program |
affiliate_unavailable | 503 | affiliate program |
agent_budget_exceeded | 403 | billing |
agent_disabled | 409 | agents |
agent_forbidden | 403 | every route |
already_enrolled | 409 | affiliate program |
already_paid | 409 | one-time send |
already_referred | 409 | affiliate program |
api_not_configured | 503 | every route |
approval_consumed | 409 | approvals |
approval_decided | 409 | approvals |
approval_expired | 409 | approvals |
approval_mismatch | 409 | approvals |
approval_not_granted | 409 | approvals |
approval_required | 403 | approvals, faxes, one-time send |
approval_self_decision | 403 | approvals |
billing_conflict | 409 | billing |
billing_not_configured | 503 | billing, provider callbacks |
billing_request_rejected | 422 | billing |
billing_unavailable | 503 | billing |
blocked_destination | 403 | one-time send |
budget_exceeded | 403 | billing |
check_refused | 422 | webhook checker |
code_not_found | 404 | affiliate program |
code_taken | 409 | affiliate program |
code_window_closed | 409 | affiliate program |
confirm_mismatch | 422 | numbers |
conflict | 409 | every route |
connect_not_in_country | 422 | affiliate program |
connect_unavailable | 503 | affiliate program |
conversion_failed | 422 | documents |
country_locked | 409 | affiliate program |
coverage_on_request | 422 | numbers |
csrf_invalid | 403 | every route |
dispute_open | 403 | faxes |
document_expired | 410 | documents |
document_hash_mismatch | 409 | approvals, faxes, one-time send |
document_not_rendered | 409 | extraction |
document_too_large | 422 | one-time send |
encrypted_pdf | 422 | documents |
environment_not_billable | 403 | billing |
idempotency_key_conflict | 409 | every route |
image_too_large | 422 | documents |
inbox_item_expired | 410 | inbox |
insufficient_balance | 402 | extraction, faxes, numbers |
internal_error | 500 | every route |
invalid_code | 422 | affiliate program |
invalid_contact | 422 | affiliate program |
invalid_destination | 422 | every route |
invalid_payout_details | 422 | affiliate program |
invalid_request | 400 or 422 | every route |
invalid_review_access | 401 | dashboard sign-in |
invalid_signature | 400 | provider callbacks |
invalid_tax_form | 422 | affiliate program |
invalid_token | 401 | every route |
inventory_rejected | 409 or 422 | numbers |
invitation_email_mismatch | 403 | dashboard sign-in |
last_owner | 409 | dashboard sign-in |
link_canceled | 409 | one-time send |
link_code_wrong | 422 | dashboard sign-in |
link_expired | 409 | dashboard sign-in, one-time send |
link_invalid | 404 | dashboard sign-in, one-time send |
link_other_session | 409 | dashboard sign-in, one-time send |
link_session_ended | 409 | dashboard sign-in |
link_used | 409 | dashboard sign-in, one-time send |
live_provider_unavailable | 503 | faxes |
mail_not_configured | 503 | provider callbacks |
method_not_allowed | 405 | every route |
not_cancelable | 409 | faxes |
not_enrolled | 404 | affiliate program |
not_found | 404 | every route |
number_in_use | 409 | numbers |
number_not_ready | 409 | numbers |
number_quarantined | 409 | numbers |
number_release_rejected | 409 or 422 | numbers |
number_taken | 409 | numbers |
oauth_denied | 400 | dashboard sign-in |
oauth_email_unverified | 403 | dashboard sign-in |
oauth_exchange_failed | 422 | dashboard sign-in |
oauth_identity_incomplete | 422 | dashboard sign-in |
oauth_state_invalid | 400 | dashboard sign-in |
oauth_state_missing | 400 | dashboard sign-in |
oauth_unavailable | 503 | dashboard sign-in |
ocr_disabled | 409 | extraction |
one_time_unavailable | 503 | one-time send |
order_closed | 409 | one-time send |
organization_deleted | 410 | every route |
origin_not_allowed | 403 | every route |
own_code | 422 | affiliate program |
owner_required | 403 | affiliate program, dashboard sign-in |
page_limit_exceeded | 422 | documents, extraction |
passkey_challenge_unknown | 400 | dashboard sign-in |
passkey_exists | 409 | dashboard sign-in |
passkey_invalid | 401 | dashboard sign-in |
passkey_registration_invalid | 400 | dashboard sign-in |
passkey_revoked | 401 | dashboard sign-in |
passkey_unknown | 401 | dashboard sign-in |
payload_too_large | 413 | every route |
payment_declined | 402 | billing |
policy_managed | 409 | policies |
port_order_rejected | 409 or 422 | numbers |
portability_rejected | 409 or 422 | numbers |
provider_not_configured | 503 | dashboard sign-in, provider callbacks |
provider_timeout | 503 | numbers |
provider_unavailable | 503 | numbers |
quote_consumed | 409 | approvals, faxes, one-time send |
quote_expired | 409 | approvals, faxes, one-time send |
quote_pricing_mismatch | 409 | faxes |
rate_limited | 429 | every route |
reauth_required | 403 | every route |
render_unavailable | 503 | documents |
run_finished | 409 | affiliate program |
sandbox_only | 403 | sandbox |
scope_missing | 403 | every route |
sender_not_owned | 422 | numbers |
session_required | 403 | affiliate program |
step_up_required | 403 | approvals |
tax_form_not_needed | 409 | affiliate program |
tax_form_too_large | 413 | affiliate program |
temporarily_unavailable | 503 | webhook checker |
terms_version_mismatch | 422 | affiliate program |
too_many_pages | 422 | one-time send |
unauthenticated | 401 | every route |
unsupported_characters | 422 | every route |
unsupported_destination | 422 | billing, one-time send, policies |
unsupported_format | 422 | documents, one-time send |
user_disabled | 403 | dashboard sign-in, faxes |
workspace_required | 403 | records export |
Why is a failed fax not an HTTP error?
A send answers 201 with a job in queued. What happens after is a state on the job, carried by events and webhooks, not an HTTP error. The glossary defines each state in a few sentences you can quote.
| State | Do |
|---|---|
| queued, active | wait for the webhook or poll GET /v1/faxes/{id}. A fax takes a minute or more on the line. Busy and no answer are tried again by the service, three attempts in all |
| delivered | read the receipt and store the provider reference |
| partial | read pages_sent. failure_code is partial_delivery. Decide whether to send the missing pages as a new fax. The service never retransmits on its own. In test a one-page fax to the sandbox number +15550000003 ends failed with the same code |
| failed | read failure_code: busy, no_answer, invalid_number, render_failed, provider_error, canceled. In test it is partial_delivery for a one-page fax to the sandbox number +15550000003, whose call drops before its page. Nothing was charged |
| unknown | wait. failure_code says why, for example callback_missing or provider_timeout. The hold stays and the reconcile tick keeps asking the provider. Do not send again from your side: a duplicate fax is the one outcome worse than a late one. If it stays unknown, write to us with the job id |
How do I avoid sending a fax twice?
Send every mutating call with an Idempotency-Key, derived from your own record such as the order id. A timeout on your side then becomes a retry that returns the same job. Never create a new quote and send after a timeout without first reading the job list for your key.
From the blog
Start in test mode. It is free.
A test API key works in test mode only. Every outcome can be rehearsed there before a wallet is funded.