Error Reference

Every error code returned by AuthProof APIs, grouped by HTTP status.

All error responses use the shape { "error": "<code>", "message": "<human-readable>" }. Rate-limited responses (429) include a Retry-After header.

400 — Bad Request

Code	Message	Endpoint(s)
missing_fields	projectId and walletAddress are required	/api/agents/register, /api/agents/request-access
missing_params	walletAddress and projectId query params required	/api/agents/request-access (GET)
invalid_wallet_address	Must be a valid 0x address (42 chars)	/api/agents/*, /api/projects/[id]/wallet-overrides
invalid_name	Project name must be 1-100 characters	/api/projects (POST)
invalid_slug	Slug must be 3-50 chars, lowercase alphanumeric and hyphens	/api/projects (POST)
invalid_origins	Allowed origins must be an array of at most 50 entries	/api/projects (POST)
invalid_rate_limit_requests	Rate limit requests must be at most 1,000,000	/api/projects/[id]/policies
invalid_rate_limit_window	Rate limit window must be at most 86400 seconds	/api/projects/[id]/policies
invalid_nft_contract	NFT contract address must be a valid Ethereum address	/api/projects/[id]/policies
invalid_allowlist_contract	Allowlist contract address must be a valid Ethereum address	/api/projects/[id]/policies
invalid_nft_chain	Unsupported chain ID for NFT gate	/api/projects/[id]/policies
invalid_allowlist_chain	Unsupported chain ID for allowlist	/api/projects/[id]/policies
invalid_webhook_url	webhookUrl must be a valid HTTPS URL	/api/agents/request-access
invalid_status	Status must be 'active' or 'revoked'	/api/projects/[id]/agents/[agentId]
agent_not_active	Only active agents can rotate keys	/api/projects/[id]/agents/[agentId]/rotate
name_required	Agent name is required	/api/projects/[id]/agents (POST)
name_too_long	Agent name must be 100 characters or fewer	/api/projects/[id]/agents (POST)
key_id_required	keyId is required in request body	/api/projects/[id]/api-keys, /api/user/api-keys

401 — Unauthorized

Code	Message	Endpoint(s)
unauthorized	Sign in or provide an API key	All session-protected routes
invalid_api_key	API key not recognized	Routes accepting Bearer sa_key_... or sa_user_...
api_key_expired	API key has expired	Routes accepting Bearer tokens

401 — ERC-8128 Signature Errors

Returned by endpoints protected with withAuthProof or expressAuthProof. All include an accept-signature response header with the correct signing parameters.

Code	Message	Endpoint(s)
replay	Nonce already consumed — this request was already used	ERC-8128 protected routes
expired	Signature expired (older than maxValiditySec)	ERC-8128 protected routes
bad_time	Signature timestamp is invalid	ERC-8128 protected routes
not_yet_valid	Signature is not yet valid (future timestamp)	ERC-8128 protected routes
validity_too_long	Signature validity exceeds server maximum (300s)	ERC-8128 protected routes

402 — Payment Required

When credits are exhausted, the response includes quoteEndpoint, verifyEndpoint, and projectId so agents can auto-pay with USDC on-chain. The SDK's createAutoPayment handles this automatically.

Code	Message	Endpoint(s)
credits_exhausted	No credits remaining. Includes payment instructions for auto-pay.	ERC-8128 protected routes
payment_required	On-chain payment required to access this resource.	/api/demo/paid-echo
invalid_payment_receipt	Payment receipt missing, invalid, or already consumed.	/api/demo/paid-echo
payments_unavailable	Autonomous payments not configured on this server.	/api/autonomous/payments/*
quote_not_found	Payment quote not found.	/api/autonomous/payments/verify
quote_expired	Payment quote has expired (5-min TTL).	/api/autonomous/payments/verify
transaction_not_found	Could not find transaction on the configured network.	/api/autonomous/payments/verify
transaction_failed	Transaction did not succeed on-chain.	/api/autonomous/payments/verify
wrong_sender	Transaction sender does not match the quoted wallet.	/api/autonomous/payments/verify
transfer_not_found	No matching USDC transfer found for this quote.	/api/autonomous/payments/verify

403 — Forbidden

Code	Message	Endpoint(s)
plan_limit_reached	Your plan allows N project(s)/agent(s). Upgrade to create more.	/api/projects, /api/agents/register, /api/agents/request-access
wrong_project	API key does not belong to this project	Routes accepting Bearer sa_key_...
origin_not_allowed	Origin is not allowed for this project	ERC-8128 protected routes
chain_not_allowed	Chain is not enabled for this project	ERC-8128 protected routes
missing_chain_client	No RPC client configured for this chain	ERC-8128 protected routes
allowlist_rejected	Wallet is not on the required on-chain allowlist	ERC-8128 protected routes
nft_required	Wallet does not hold the required NFT	ERC-8128 protected routes
wallet_blocked	This wallet has been blocked from accessing this project	ERC-8128 protected routes

404 — Not Found

Code	Message	Endpoint(s)
not_found	Resource not found (or you don't have access)	Session/API-key protected routes
project_not_found	No project with that ID	/api/agents/request-access, /api/demo/echo
invalid_invite_code	Invite code not found	/api/agents/register
key_not_found	API key not found	/api/projects/[id]/api-keys, /api/user/api-keys

409 — Conflict

Code	Message	Endpoint(s)
slug_taken	You already have a project with this slug	/api/projects (POST)
already_registered	This wallet is already registered for this project	/api/agents/request-access
address_already_registered	This wallet address is already registered in this project	/api/projects/[id]/agents/[agentId]/rotate

410 — Gone

Code	Message	Endpoint(s)
invite_already_used	This invite code has already been claimed	/api/agents/register
invite_expired	This invite code has expired	/api/agents/register

429 — Too Many Requests

All 429 responses include a Retry-After header (in seconds).

Code	Message	Endpoint(s)
rate_limited	Too many requests. Please try again later.	IP-limited public endpoints + per-wallet middleware

500 — Internal Server Error

Code	Message	Endpoint(s)
internal_error	Something went wrong on the server	All routes (catch-all)