{"version":"1.0.0","description":"Every error code this API can return, with the HTTP status it travels on, whether a retry can help, and what to do about it. An agent that reads this document can self-correct instead of retrying forever.","error_taxonomy":"https://x402.synthexforge.com/v1/errors","error_shape":{"description":"The JSON body every error response carries.","properties":{"error":"Stable machine-readable code. Matches `code` here.","error_reason":"Finer-grained reason. Also matches `code`.","error_message":"Human-readable text. Not for control flow.","x402Version":"The x402 protocol version."}},"retry_semantics":"`retryable: true` means the identical request may succeed later. `retryable: false` means it will not — change the request or the payment first.","count":14,"codes":[{"code":"payment_required","http_status":402,"meaning":"The route is paid and the request carried no valid payment.","retryable":false,"fix":"Read the `Payment-Required` response header, sign the EIP-3009 authorization it describes, and resend with an `X-PAYMENT` header. See /v1/errors and the operation's x-payment-info."},{"code":"pass_expired","http_status":402,"meaning":"The `X-Zeux-Pass` token's expiry is in the past.","retryable":false,"fix":"Purchase a new pass at POST /v1/pass/purchase, or pay per call."},{"code":"pass_exhausted","http_status":402,"meaning":"The pass has no calls remaining.","retryable":false,"fix":"Purchase a new pass at POST /v1/pass/purchase, or pay per call."},{"code":"pass_scope","http_status":402,"meaning":"The pass does not cover a route priced this high.","retryable":false,"fix":"Pay per call, or use a pass whose scope covers this price. Check `scope` at POST /v1/pass/balance."},{"code":"pass_invalid_signature","http_status":402,"meaning":"The pass token's Ed25519 signature did not verify.","retryable":false,"fix":"The token is malformed or tampered with. Re-issue the token from the purchase response."},{"code":"pass_malformed","http_status":402,"meaning":"The pass token is not a well-formed `ps1.<payload>.<sig>` token.","retryable":false,"fix":"Send the token exactly as returned by POST /v1/pass/purchase."},{"code":"pass_unknown","http_status":402,"meaning":"The pass is not known to this service.","retryable":false,"fix":"The token references a pass this service did not issue, or the store was reset. Pay per call."},{"code":"validation_error","http_status":422,"meaning":"The request body or query failed FastAPI/Pydantic validation.","retryable":false,"fix":"Read the `detail` array: each entry names the `loc` path of the offending field. The operation's requestBody schema states the field types."},{"code":"bad_request","http_status":400,"meaning":"The request was well-formed but its CONTENT failed validation — a value the route needs was empty, or the body could not be parsed into the shape the route expects.","retryable":false,"fix":"Read `detail`: it names the value the route rejected (for example `url is required`). Send a non-empty value for the field the detail names. This differs from 422, which means the request did not match the declared schema at all."},{"code":"method_not_allowed","http_status":405,"meaning":"The HTTP method is not supported on this path.","retryable":false,"fix":"Use one of the methods the operation declares. The OpenAPI document lists the supported method per path."},{"code":"not_found","http_status":404,"meaning":"No record matches the identifier in the path.","retryable":false,"fix":"Check the identifier. Verify routes answer `found: false` with 200 instead of 404 when the id is well-formed but unknown."},{"code":"payment_required_invalid","http_status":402,"meaning":"The payment was present but did not satisfy the requirements (wrong amount, wrong network, wrong asset, or an unverified signature).","retryable":false,"fix":"Compare the `accepts` block in the 402 challenge against the payment you signed: the amount, network, asset and payTo must match exactly."},{"code":"internal_error","http_status":500,"meaning":"The service failed to handle a request it should have handled.","retryable":true,"fix":"Retry with the same body. If it persists, the fault is ours."},{"code":"service_unavailable","http_status":503,"meaning":"The service is temporarily unable to handle the request.","retryable":true,"fix":"Retry after a short delay, honouring Retry-After if present."}],"served_at":"2026-10-22T08:01:08Z"}