Errors and limits

Common errors

You see	Why	What to do
`createGuard` throws	`baseUrl` is missing or is not a valid address.	Set `baseUrl: "https://api.warns.xyz"`.
`GuardConfigurationError`, `UNAUTHORIZED`	The key is wrong, or was revoked.	Create a key in Settings, API keys.
`GuardConfigurationError`, `AGENT_NOT_FOUND`	No agent has this `agentId` in the key's environment.	Check the agent id, and that the key and the agent are both Test or both Live.
`PaymentBlockedError`, `PAYER_NOT_REGISTERED`	The paying wallet is not registered on the agent.	In Agents, click Add wallet on the agent and enter that address. Remove a wrong one with the cross next to it.
`BindingViolationError` about `validBefore`	The merchant asked for an authorization that stays valid longer than 120 seconds.	Nothing: the guard refuses long windows in every mode, on purpose.
`PaymentBlockedError`, `RATE_LIMITED`	Too many calls in a short time.	Slow down. See the limits below.
`GuardUnavailableError`	Warns did not answer within 2 seconds.	Check your network. See Outages and fallback.

Every error the API returns has the same shape: { "error": { "code", "message", "requestId" } }. Send the requestId along when you write to us.

What Warns supports

What	Supported
Protocol	x402 version 2, scheme `exact`, with an EIP-3009 authorization, including Circle Gateway's batched option on Arc testnet; direct USDC transfers through the HTTP API
Networks	Base Sepolia (`eip155:84532`) and Arc testnet (`eip155:5042002`) with a test key, monitor and protect; Base (`eip155:8453`) with a live key, monitor only during early access. A key used on a network of the other environment gets `NETWORK_ENVIRONMENT_MISMATCH`
Asset	USDC: `0x036CbD53842c5426634e7929541eC2318f3dCF7e` on Base Sepolia, `0x3600000000000000000000000000000000000000` on Arc testnet, `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` on Base
Authorization window	120 seconds at most; for Circle Gateway, between 3 days and 7 days and 1 hour

Any other payment option is refused by the guard before it reaches Warns, whatever the agent's mode.

Limits

What	Limit, per API key
Decisions	60 in a burst, then 20 per second
Settlement and fallback reports	120 in a burst, then 40 per second
Other calls	30 in a burst, then 5 per second
Request body	64 KB
Payment request header	16 KB, with 32 payment options at most

Over a limit, the API answers 429 and the guard throws a PaymentBlockedError with the code RATE_LIMITED. The traps have their own limit, per IP address.

The beta

Warns is free during the beta. On Base Sepolia, use test wallets. On Base mainnet, Warns only monitors: it never blocks a payment, and it does not prevent a loss. The beta terms apply. For anything else, write to hello@warns.xyz.