Understand errors and retry safely

An idempotency key identifies one logical request. Reusing the same key with the same request lets Onchain Router recover the existing result without calling the model or charging the wallet again.

Safe to correct and retry

• Invalid JSON, model, or output ceiling: fix the request and obtain a new quote.
• Hypertext Transfer Protocol (HTTP) status 402: check the payment terms, sign, and retry the identical body.
• Expired authorization: obtain a new quote and authorization.
• empty_provider_response: increase max_tokens, obtain a fresh quote, and retry; the failed attempt is not settled.
• Definite provider rejection before acceptance: correct the cause and retry with a new idempotency key.
• wallet_request_cap_exceeded: lower the requested output ceiling and obtain a new quote, or ask the operator to review the policy.

Do not retry blindly

• provider_outcome_unknown
• settlement_unknown
• lost connection after wallet authorization
• timeout after the provider or facilitator may have accepted work

Retry the same request with the same idempotency key to recover the stored state. Do not create a new request until the existing operation is known to have failed definitively.

Idempotency rules

The first-party clients send x-idempotency-key, and x402 payment identifiers may provide an additional protocol identity. Repeating an identical request returns the original result or stored state without a second model call or charge. Reusing the key with a changed request returns HTTP status 409.

Redis loss does not weaken these guarantees because PostgreSQL owns the execution lease and authorization fingerprint.