Error handling

Status codes are consistent across the MCP axiom_request_attestation tool and the REST POST /v1/topup endpoint. MCP tool errors arrive as JSON-RPC errors whose HTTP status is mirrored in the error data.

Status codes

Code	When	What to do
`200`	Success.	Proceed.
`400`	Malformed top-up (`invalid_json`, `invalid_amount`, `invalid_x_payment`, `topup_not_allowed_for_tier`).	Fix the request body / payment.
`401`	API key missing, malformed, or not recognized.	Check `Authorization: Bearer axm_live_…`.
`402`	Quota exhausted (attestation requests) — or payment required / `payment_invalid` (top-up).	Top up, or re-sign the payment.
`403`	API key recognized but inactive.	Contact Axiom Stack to reactivate.
`409`	`already_credited` — this settled top-up payment was already credited.	No action; quota already reflects it.
`422`	`amount_below_minimum` — the top-up amount credits 0 attestations at your tier rate.	Increase the amount (see Pricing).
`502`	`settlement_failed` / `onchain_unverified` — settlement could not be confirmed.	You were not charged. Retry.
`503`	Backend / facilitator temporarily unavailable.	Retry with backoff.

Quota exhausted is 402, not 429. Earlier/internal material may show 429; the live attestation path returns 402 with a hint to POST /v1/topup (changed when customer-pays-USDC shipped). Document and handle 402 for quota.

Auto-credit on failure

If an attestation request is admitted (quota consumed) but then fails — provider-fetch failure, on-chain reject, or timeout — Themra credits one attestation back to your quota automatically. You are not charged for attestations that don't complete. (A single failed request credits at most once.)

No key-enumeration leak

An unknown key and a missing/malformed key both return 401 — the API never reveals whether a specific key exists. Only a recognized-but-inactive key returns 403.

Retry guidance

502 / 503 are transient — retry with exponential backoff. For top-ups, 502 means no charge occurred, so it is safe to retry.
402 (quota) is not transient — top up before retrying.
401 / 403 / 400 / 422 are caller errors — fix the request; don't blind-retry.
Attestation timeout (default 90 s poll): the request may still land — your quota is auto-credited if it didn't; retry safely.