Skip to main content
Every error response from the API is JSON. There are two shapes: Catcher errors (auth, billing, routing, body parsing) return a structured object: 
{
  "error": "payment_required",
  "message": "Insufficient credits: this call needs $0.01 but your balance is $0.00.",
  "fix": "Add funds (minimum $5.00, card or crypto) in the dashboard at https://dashboard.chipotle.litprotocol.com/dapps/dashboard/ or via POST /core/v1/billing/create_payment_intent. Check your balance with GET /core/v1/billing/balance.",
  "docs_url": "https://developer.litprotocol.com/management/pricing"
}
Endpoint-specific failures (a contract revert, an execution error) return a JSON string with the error message and the matching HTTP status: 
"Permission denied"
Robust clients should branch on the HTTP status code first and treat the body as diagnostic detail.

​
Status codes

StatuserrorWhat it meansWhat to do
400 Bad Requestbad_requestThe body is malformed JSON or a parameter has the wrong shape.Compare your request against the OpenAPI spec.
401 UnauthorizedunauthorizedNo API key was sent, or the key does not resolve to any account (typo’d, revoked, or never created).Send the key via X-Api-Key or Authorization: Bearer. Verify it with GET /core/v1/account_exists.
402 Payment Requiredpayment_requiredYour account exists but its credit balance cannot cover this operation. The message includes the required amount and your balance.Add funds — card or crypto — or POST /core/v1/billing/create_payment_intent. Check balance with GET /core/v1/billing/balance.
403 ForbiddenforbiddenThe key is valid and funded but not permitted to do this — usually a usage key acting outside its granted groups.Inspect scopes with GET /core/v1/list_api_keys, or use the account master key. See API Keys.
404 Not Foundnot_foundNo such endpoint or resource.Browse /core/v1/swagger-ui.
422 Unprocessable Entityunprocessable_entityThe body parsed as JSON but doesn’t match the endpoint’s schema.Compare field names and types against the OpenAPI spec.
429 Too Many Requeststoo_many_requestsThe node is shedding load (CPU pressure).Retry with backoff.
500 Internal Server Errorinternal_errorSomething failed on our side.Retry; report it if persistent.
503 Service Unavailableservice_unavailableA dependency (billing, chain RPC, or the actions runtime) is temporarily down. Nothing was charged.Retry in a few seconds.

​
Billing guarantees on errors

  • Failed requests are not charged. The flat $0.01 management charge settles only after the operation succeeds. A request rejected for a bad body (400/422), missing permission (403), or a server error (5xx) costs nothing.
  • An invalid key is a 401, not a 402. You will only ever see 402 Payment Required for an account that actually exists and is short on credits.
  • Billing outages are a 503, not a 402. If Stripe or the chain RPC is unreachable, the API tells you to retry — it does not tell you to pay.

​
Common sequences

“I created an account but every call says 402.” New accounts start with no credits unless the node grants starter credits. Running Lit Actions and write/metered management calls (creating wallets, groups, usage keys) consume credits; read-only calls (list_*, account_exists, billing/balance) are free. Add funds to proceed. “My key worked yesterday and now I get 401.” The key was removed (remove_usage_api_key) or you’re sending a truncated value. Keys are shown once at creation; verify with GET /core/v1/account_exists and mint a new usage key from your account key if needed. “The error body isn’t JSON.” It is, as of API version v1.2. If you see an HTML error page you are talking to something other than the API (a proxy, a wrong URL) — check the host and path.