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.

JSON
{"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

Error codes and the action for each
CodeStatusWhat to do
invalid_token401the key is missing, revoked or malformed. Get a key from the dashboard
scope_missing403the API key lacks the scope. The message names it
agent_forbidden403an agent key is not allowed on this route. A person does this
not_found404no 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_request400 or 422the body failed validation. details lists the fields
conflict409the 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_conflict409this Idempotency-Key was used with a different body. details.resource_id names the first resource. Use a new key for a new request
not_cancelable409the fax has already ended. details.state names its state
document_expired, inbox_item_expired410the 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_deleted410the organization is being deleted. Its keys no longer work
account_suspended403sending is suspended for this account. Write to us
encrypted_pdf, unsupported_format, page_limit_exceeded422fix the document and create it again. Nothing was stored or charged
unsupported_characters422text, 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_large422the 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_unavailable503the HTML renderer is down. Retryable
live_provider_unavailable503live sending is not enabled on this server yet, so live quotes, sends and number orders are refused. Test keys keep working. Not retryable
unsupported_destination422no 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_open403live 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_destination422the number is not a valid E.164 number. Correct it
sender_not_owned422POST /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_consumed409this quote already created a fax. details names it. Read that fax
document_hash_mismatch409the document changed or was deleted after the quote. Quote again
quote_expired409quote again. Quotes last ten minutes
insufficient_balance402top up the wallet. The provider was not called
budget_exceeded, agent_budget_exceeded403the cap for the period is reached. A person raises it or waits
approval_required403a live send with no approval and no allowing policy. Ask a person
approval_*409see the approvals page. Quote and ask again
sandbox_only, environment_not_billable403the route is for the other kind of key.
payload_too_large413the 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_limited429600 requests a minute per key, 3,000 while the Agent workspace plan is active. Retryable after RateLimit-Reset
workspace_required403the 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_rejected409 or 422the carrier refused the request. Read its reason in message. Correct the request before trying again
number_not_ready409the carrier has not finished setting up the number. Wait before requesting its release
number_taken, number_quarantined409the number is on an account, or was released in the last 30 days. Choose another number
number_in_use409a fax from this number is still in flight. Wait for it to end before releasing the number
agent_disabled409the agent is disabled. A person enables it before a key is made for it
billing_request_rejected422the payment provider refused the request. Read message and correct the request
payment_declined402the payment was refused. Read message and use another payment method
billing_conflict409the payment provider found a conflicting request. Check the existing payment before trying again
oauth_exchange_failed, oauth_identity_incomplete422start a new sign-in or use an email link
ocr_disabled409live extraction is disabled. Repeating the request cannot enable it
document_not_rendered409the document has no page images to read. Create it again
billing_unavailable, temporarily_unavailable, provider_timeout, provider_unavailable, oauth_unavailable503retry after the service recovers. Reuse the same Idempotency-Key for a mutation
internal_error500retryable. 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.

Every error code, its HTTP status and where it is met
CodeStatusWhere
account_not_in_good_standing403affiliate program
account_suspended403faxes, one-time send
affiliate_ended409affiliate program
affiliate_not_active403affiliate program
affiliate_suspended409affiliate program
affiliate_unavailable503affiliate program
agent_budget_exceeded403billing
agent_disabled409agents
agent_forbidden403every route
already_enrolled409affiliate program
already_paid409one-time send
already_referred409affiliate program
api_not_configured503every route
approval_consumed409approvals
approval_decided409approvals
approval_expired409approvals
approval_mismatch409approvals
approval_not_granted409approvals
approval_required403approvals, faxes, one-time send
approval_self_decision403approvals
billing_conflict409billing
billing_not_configured503billing, provider callbacks
billing_request_rejected422billing
billing_unavailable503billing
blocked_destination403one-time send
budget_exceeded403billing
check_refused422webhook checker
code_not_found404affiliate program
code_taken409affiliate program
code_window_closed409affiliate program
confirm_mismatch422numbers
conflict409every route
connect_not_in_country422affiliate program
connect_unavailable503affiliate program
conversion_failed422documents
country_locked409affiliate program
coverage_on_request422numbers
csrf_invalid403every route
dispute_open403faxes
document_expired410documents
document_hash_mismatch409approvals, faxes, one-time send
document_not_rendered409extraction
document_too_large422one-time send
encrypted_pdf422documents
environment_not_billable403billing
idempotency_key_conflict409every route
image_too_large422documents
inbox_item_expired410inbox
insufficient_balance402extraction, faxes, numbers
internal_error500every route
invalid_code422affiliate program
invalid_contact422affiliate program
invalid_destination422every route
invalid_payout_details422affiliate program
invalid_request400 or 422every route
invalid_review_access401dashboard sign-in
invalid_signature400provider callbacks
invalid_tax_form422affiliate program
invalid_token401every route
inventory_rejected409 or 422numbers
invitation_email_mismatch403dashboard sign-in
last_owner409dashboard sign-in
link_canceled409one-time send
link_code_wrong422dashboard sign-in
link_expired409dashboard sign-in, one-time send
link_invalid404dashboard sign-in, one-time send
link_other_session409dashboard sign-in, one-time send
link_session_ended409dashboard sign-in
link_used409dashboard sign-in, one-time send
live_provider_unavailable503faxes
mail_not_configured503provider callbacks
method_not_allowed405every route
not_cancelable409faxes
not_enrolled404affiliate program
not_found404every route
number_in_use409numbers
number_not_ready409numbers
number_quarantined409numbers
number_release_rejected409 or 422numbers
number_taken409numbers
oauth_denied400dashboard sign-in
oauth_email_unverified403dashboard sign-in
oauth_exchange_failed422dashboard sign-in
oauth_identity_incomplete422dashboard sign-in
oauth_state_invalid400dashboard sign-in
oauth_state_missing400dashboard sign-in
oauth_unavailable503dashboard sign-in
ocr_disabled409extraction
one_time_unavailable503one-time send
order_closed409one-time send
organization_deleted410every route
origin_not_allowed403every route
own_code422affiliate program
owner_required403affiliate program, dashboard sign-in
page_limit_exceeded422documents, extraction
passkey_challenge_unknown400dashboard sign-in
passkey_exists409dashboard sign-in
passkey_invalid401dashboard sign-in
passkey_registration_invalid400dashboard sign-in
passkey_revoked401dashboard sign-in
passkey_unknown401dashboard sign-in
payload_too_large413every route
payment_declined402billing
policy_managed409policies
port_order_rejected409 or 422numbers
portability_rejected409 or 422numbers
provider_not_configured503dashboard sign-in, provider callbacks
provider_timeout503numbers
provider_unavailable503numbers
quote_consumed409approvals, faxes, one-time send
quote_expired409approvals, faxes, one-time send
quote_pricing_mismatch409faxes
rate_limited429every route
reauth_required403every route
render_unavailable503documents
run_finished409affiliate program
sandbox_only403sandbox
scope_missing403every route
sender_not_owned422numbers
session_required403affiliate program
step_up_required403approvals
tax_form_not_needed409affiliate program
tax_form_too_large413affiliate program
temporarily_unavailable503webhook checker
terms_version_mismatch422affiliate program
too_many_pages422one-time send
unauthenticated401every route
unsupported_characters422every route
unsupported_destination422billing, one-time send, policies
unsupported_format422documents, one-time send
user_disabled403dashboard sign-in, faxes
workspace_required403records 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.

A fax job starts as queued. It becomes active when the service hands it to the carrier. A queued job that is canceled ends as failed. An active job moves to one of four states. Delivered: the carrier gave evidence. Failed: the fax was not delivered and nothing is charged. Partial: some pages went through, with evidence. Unknown: no result came by the deadline. The service never retransmits a partial or an unknown job. It keeps asking the carrier about an unknown job, and the answer ends that job as delivered, partial or failed. queued active delivered evidence from the carrier failed not delivered, not charged partial some pages, with evidence unknown no result by the deadline canceled handed to the carrier never retransmitted by the service An unknown job ends when the carrier answers.
What your code should do per state
StateDo
queued, activewait 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
deliveredread the receipt and store the provider reference
partialread 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
failedread 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
unknownwait. 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.

Get an API key Read the quickstart