Every error, visually

✕ validation_error

A field failed schema validation; `reason` lists `field: problem` pairs.

✕ invalid_request

Body was well-formed JSON but not usable as sent.

✕ invalid_page_count

page_count is not a whole number of at least 1.

✕ page_limit_exceeded

The document is longer than the 12-page maximum.

✕ tracking_included

Tracking was added to a class that already includes it — first_class only.

✕ empty_document

The PDF or text contains nothing printable.

✕ unsupported_characters

The letter text contains characters the chosen font cannot print (e.g. CJK, Arabic, or emoji). Upload as a PDF instead to send it as-is.

✕ invalid_pdf

The bytes aren't a readable PDF.

✕ invalid_base64

pdf_base64 is not valid base64.

✕ low_text_density

Scanned-image PDF. Text documents only at launch.

✕ file_too_large

PDF is over the 10MB cap (413 when PUT to the upload route).

✕ pdf_fetch_failed

pdf_url wasn't publicly fetchable as a PDF.

✕ pdf_required

This piece format needs a PDF and none was supplied.

✕ blocked_address

pdf_url points at a private, reserved, or non-http(s) address and was refused.

✕ dns_failed

pdf_url's host did not resolve.

✕ redirect_limit

pdf_url redirected too many times.

✕ invalid_upload_key

upload_key isn't a key this server issued.

✕ upload_not_found

The upload_key expired or was already consumed.

✕ unknown_pack

No credit pack with that id.

✕ invalid_stars

A review was submitted with stars outside 1–5.

✕ unsupported_mail_class

The rail that prints this piece does not offer that mail class.

✕ unsupported_piece

The rail does not produce that piece format.

✕ unknown_format

No such piece format.

✕ class_unavailable_for_format

That mail class cannot carry that physical piece — a postcard cannot go certified.

✕ invalid_key

An Authorization header was sent and did not verify. Omit it entirely to call anonymously.

✕ key_disabled

The key is real and has been turned off.

✕ insufficient_scope

Valid key, but it does not carry the scope this route needs (`reason` names what it does carry).

✕ key_store_unavailable

The key could not be checked, so it is not honoured. A credential we cannot verify is refused, never downgraded.

✕ confirmation_required

No confirmation_token on a surface that requires one. Quote first; a send is never the first call.

✕ confirmation_malformed

Not a paperplane quote token.

✕ confirmation_invalid

Signature check failed — the token was altered or signed by another deployment.

✕ confirmation_expired

Past its 30-minute window. Quote again.

✕ confirmation_mismatch

Valid token, different letter — recipient, class, colour, tracking, content, or price changed since the quote.

✕ confirmation_used

Already redeemed. **The letter you quoted was sent.** This is replay protection working; do not resend.

✕ quote_content_required

A quote carrying no letter content cannot mint a token. A token binds a quote to one specific letter, so one bound to no document is not a weaker quote -- it is a blank cheque for any document the send path cannot fingerprint.

✕ confirmation_unavailable

No signing secret configured, so no token could be minted or checked.

✕ invalid_capability

The token is missing, malformed, or was issued for a different order or action.

✕ expired_capability

Past its 7-day window. Gone, not forbidden — create a new order for a fresh pair.

✕ capability_unavailable

No signing secret configured, so capability tokens cannot be issued or checked.

✕ unknown_code

No credit account with that code (404 from the balance lookup, 402 when used to pay for an order).

✕ insufficient_balance

The credit code exists but cannot cover this order; `next` states the balance.

✕ x402_not_configured

Agent payments are off on this deployment. Use /v1/credits/checkout or a credit_code.

✕ payment_required

No X-PAYMENT header (or MCP `payment_header`) was supplied; the response body is a full x402 payment-required challenge — sign it and resubmit with the header set.

✕ region_unsupported

The x402 stablecoin lane is hidden in this region (New York) because the underlying Stripe payment method is not offered there; use /v1/credits/checkout or a credit_code.

✕ x402_verify_failed

The facilitator would not verify the X-PAYMENT payload.

✕ x402_settle_failed

Verification passed and settlement did not. Nothing was minted.

✕ x402_payment_invalid

The X-PAYMENT header is not a payload we can read.

✕ payments_not_configured

This deployment can't take payments right now.

✕ no_checkout_url

Stripe accepted the session and returned no URL to send the payer to.

✕ no_client_secret

Stripe accepted an embedded-checkout session (checkout_ui_mode: "embedded") and returned no client_secret to mount.

✕ not_found

No order with that id. Sandbox orders are cleared on redeploy.

✕ too_late

Already handed to the carrier; the cancellation window is closed.

✕ not_reviewable

That order is not delivered, or has already been reviewed.

✕ not_held

A review action on an order that is not held.

✕ address_undeliverable

USPS verification rejected the recipient address; `reason` says why.

✕ rejected

The fulfillment rail terminally refused the piece. Not retryable — fix the piece.

✕ idempotency_key_in_flight

An earlier request with this `Idempotency-Key` has not finished. Retry with **the same key** after `Retry-After` to receive that request's order -- retrying with a new key is the intuitive move and it mails a second letter.

✕ rate_limited

Per-IP throttle on a guest endpoint. Honour Retry-After.

✕ velocity_limit

Per-sender send cap (5/day, 20/month).

✕ spend_limit

Per-credential spend cap ($50/day, $200/month).

✕ caller_unidentified

We could not identify the caller well enough to hold it to a cap, so the send is refused rather than uncapped.

✕ unavailable

Transient fulfillment failure. Safe to retry.

✕ rail_unavailable

Valid request, but no rail is currently configured to mail it.

✕ limit_check_unavailable

The cap ledger was unreachable, so the send is refused rather than run uncapped.

✕ audit_unavailable

The audit trail was unreachable. We do not mail what we cannot attribute.

✕ below_cost_floor

This piece cannot be sent at its current price — a rail cost or plan-tier fault on our side, not your request. Nothing was charged; try a different format or mail class, or contact support.

✕ retry_unsafe

The rail did not confirm the send and cannot be asked, so we refused to retry rather than risk a second physical piece. Nothing was sent and nothing was charged. **Do not auto-retry** — resubmit only if a human has confirmed nothing arrived.

next

• → Do not auto-retry — see the error contract for the safe recovery step.

✕ submit_outcome_unknown

The rail could not tell us whether the piece reached the print facility, so it was not sent again. Nothing was charged, but a piece may already be in the mail. **Do not auto-retry** — resubmitting could produce a duplicate.

next

• → Do not auto-retry — see the error contract for the safe recovery step.

✕ internal

Unexpected. Retry once, then report it with the response body.