Getting started

Errors

All non-2xx responses share the same JSON shape. The HTTP status code stays canonical; the body's code field is for programmatic branching.

Error shape

Example 401 body
{
  "error": "invalid_api_key"
}

A few endpoints add fields. rate_limited bodies include resetAt (Unix ms timestamp). invalid_address bodies in the public demo include the offending input.

Error codes

StatusCodeMeaning
400
invalid_json
Request body wasn't valid JSON
400
invalid_address
Wallet address isn't a valid Ethereum or Solana address
400
invalid_tier
Unrecognised tier value on admin endpoints
401
missing_api_key
Authorization header is missing or malformed
401
invalid_api_key
Key is unknown or revoked
401
missing_token
Dashboard endpoint received no Privy token
401
invalid_token
Privy access token failed verification
404
not_found
Unknown protocol slug or resource
429
rate_limited
Per-minute or monthly quota hit. See Retry-After.
500
internal_error
Unhandled server error. Safe to retry once.
503
server_not_configured
An optional integration (Privy, etc.) hasn't been wired on this deployment

Retrying

500 and 503 are safe to retry with exponential backoff. 429 responses always carry a Retry-After header — respect it.

400/401/404 reflect a problem in the request itself; retrying without changes won't help.