Errors

Every 402, 403, and 451 body carries an error object with code, message, hint, and docsUrl. The catalog below is generated from ERROR_CODES in @tollgatepay/core/types/errors at build time.

Error slugs (the tail segment of docsUrl) are stable. HTTP responses hard-code them; never rename one without a migration plan.

Catalog

• NO_IOU_HEADER — Missing x-tollgate-iou header
• INVALID_IOU — IOU failed schema validation
• INVALID_SIGNATURE — EIP-712 signature did not recover to the claimed agent address
• INVALID_API_KEY — apiKeyHash in IOU did not match expected HMAC
• SALT_ROTATED — Developer salt has rotated; previously-fetched 402 response is stale
• EXPIRED_IOU — IOU deadline is in the past (or outside the clock-skew window)
• NONCE_REUSED — Nonce already consumed for this (agent, developer, path)
• INSUFFICIENT_ALLOWANCE — Agent's on-chain USDC allowance to the developer is below amountMicros
• BLACKLISTED — Agent address is blacklisted
• EXPOSURE_EXCEEDED — Agent exposure cap exceeded for this developer
• AMOUNT_NOT_MONOTONIC — IOU cumulative amount is less than the previously observed cumulative
• AMOUNT_MISMATCH — IOU delta (current - previous) does not match this request's advertised price
• NOT_EOA — Agent address has code on chain — EIP-712 signatures from contracts are not accepted
• PATH_APPEARS_DYNAMIC — Canonicalized path contains UUID/numeric segments that look dynamic
• PATH_INVALID — Request path cannot be canonicalized
• PATH_MISMATCH — IOU path does not match request path after canonicalization
• UNSUPPORTED_CHAIN — chainId is not supported
• UNSUPPORTED_CHAIN_TESTNET — Facilitator is in testnet mode — only Base Sepolia (chainId 84532) is accepted
• MODE_MISMATCH — Client/server Tollgate mode mismatch (production vs testnet)
• GEO_BLOCKED — Requests from this jurisdiction are not supported at launch
• MISSING_AUTH — Request is missing an Authorization header
• MALFORMED_KEY — Bearer key did not match the Tollgate API-key format
• UNKNOWN_KEY — Bearer key is not recognized
• KEY_REVOKED — API key has been revoked
• SCOPE_INSUFFICIENT — API key scope does not cover this route
• ACCOUNT_FROZEN — Developer account is frozen
• FACILITATOR_UNAVAILABLE — Facilitator is temporarily unreachable