Errors

Both surfaces use standard HTTP status codes. Error bodies are actionable: a recoverable error tells your agent the URL to fix it.

Status codes#

Code	Meaning
`200`	Success
`400`	Bad request: missing or invalid parameters
`401`	Missing or invalid API key (body includes signup_url)
`402`	Out of credits / no wallet (body includes topup_url)
`404`	Resource not found
`429`	Rate limit exceeded: back off and retry
`500`	Server error: the call is refunded, never billed

Out of credits#

A 402 carries everything an agent needs to recover on its own, namely what it needed, the current balance, and where to top up:

json

{
  "error": "insufficient_credits",
  "needed": 10,
  "balance": 3,
  "topup_url": "https://arkolith.com/account/credits"
}

Similarly, a 401 includes a signup_url. An agent can check its balance any time for free with account.balance.

You're never billed for a failure#

If a handler errors (a 500), the credit charge is refunded automatically. Some tools also return a no-charge result when a valid query produced nothing billable. A cluster scan might find no qualifying cluster, or a cross-venue divergence might have no overlapping market. You only pay when you get the answer the tool exists to give.

← Previous

Cross-source signals

Tool reference