Error reference

Every response a wall can return, and what to do about it.

Status codes

Code	Reason	What it means	What to do
200	—	You passed	Nothing
400	malformed envelope / bad encoding / oversized nonce	Your envelope is unparseable or has an invalid field	Fix the envelope; check field order and types
401	invalid request signature / cert: not signed by root	The envelope is well-formed but the signatures don't verify	Re-sign with the correct keys
402	authorization required	No header, and you look like an un-enrolled agent	Enroll, get a key
402	spend key required	Identity without a capability	Get a scoped spend key for this site
402	payment_required	The site has a price and you haven't paid	Settle the x402 challenge
403	audience does not match this site	Your capability is scoped to a different site	Get a capability for this site

Common verify() errors

The wall's verifier returns a specific reason string. These map to the codes above:

invalid root pub
malformed envelope
cert: bad encoding / bad pub / not signed by root
request agent does not match certificate
request nonce exceeds safe integer range
bad request signature encoding
invalid request signature
request timestamp too old / in the future
spend key required
cap: unknown version / no actions / unknown action
cap: empty audience / unknown verification_mode
cap: bad signature encoding / not signed by root
cap: online verification required (revocation + reservation not available)
cap: issued in the future / expired
cap: offline capability requires an expiry
cap: audience does not match request site
cap: holder does not match request agent
cap: request exceeds budget

Reading the response

The wall returns JSON with a human-readable reason:

{
  "error": "authorization_required",
  "reason": "spend key required",
  "site_id": "example.com",
  "suggestion": "This site is protected by MotherShy. Get a key for your agent at https://mothershy.com/access?site=example.com"
}

The X-MotherShy-Wall response header also carries the reason, so you can branch on it without parsing JSON.

One gotcha: the Cloudflare bot block

If you're testing against a *.workers.dev URL and get a 403, that may be Cloudflare's bot-block rejecting your client's User-Agent before the wall ever runs — not a wall verdict. Use curl or a browser-like User-Agent against direct/DNS-only walls to avoid this.

Next

• Concepts: verification modes
• API: wall behavior