Errors & Status Codes

Errors return a JSON body with an error message:

{ "error": "Human-readable error message." }

Status codes

Status	Meaning	What to do
`200`	Success: the audit verdict is in the body (or, with `async=true`, a `{ "status": ... }` progress body).	Read `audit.isSafe`; if the body has `status`, keep polling.
`400`	Invalid request: unknown `chain` or malformed `address`.	Fix the parameters; don’t retry as-is.
`401`	Missing or invalid API key.	Check the `X-Auth-Key` header and the key’s status.
`402`	No active subscription, or your credit allowance is exhausted.	See the `action` field (below) and top up or subscribe.
`404`	The contract is not tradable yet (no liquidity pool).	Retry once a pool exists (see below).
`429`	Spend cap reached. On `/audit-contract` the body carries `cap_usd` and `used_usd` (no `action`). On the subscribe endpoints (`POST /api/subscriptions`, `import-history`) a projected bulk cost that would cross the cap returns `action: "raise_cap"` with `required_credits` / `remaining_credits`, and nothing is subscribed.	Raise the cap in the dashboard / with your account manager; this is not a `5xx`, don’t blind-retry.
`5xx`	Temporary server error.	Retry with exponential backoff.

Not tradable yet (`404`)

Only tradable contracts are audited. If no liquidity pool exists for the contract yet, the response is a 404 with a machine-readable reason rather than a generic error:

{
  "audit": null,
  "reason": "no_liquidity_pool",
  "message": "No liquidity pool found for this token yet — only tradable contracts are audited. Retry once a pool has been created."
}

Treat this as “not ready yet”, not a hard failure. Retry once the contract has a pool.

Handling `402`

A 402 includes an action hint for what to do next:

{ "error": "Monthly credit limit reached", "action": "upgrade" }

`action`	Meaning
`subscribe`	No plan yet: choose one on the pricing page.
`add_payment`	A payment failed: update your card in the dashboard.
`resubscribe`	The subscription ended: start a new one.
`upgrade`	Out of credits for the period: upgrade or enable pay-as-you-go.
`wait`	A time-based limit is active (e.g. daily trial cap): retry after the `resets_at` in the body.
`verify_payment` / `payment_processing`	Pay-as-you-go collection in progress: no action, retry shortly.
`raise_cap`	Your own spending cap was hit: raise it in the dashboard.

Denial bodies may carry extra context fields depending on the wall (resets_at, daily_limit, grace_usd, current_period_end, subscription_status). Treat the shape as open.

Treat 400 and 401 as permanent (fix the request), and 5xx as transient (retry). For 402 and 429, surface the response to whoever manages billing; neither clears on a blind retry.

Get Started

API Reference

Reference

Programs

Resources

Status codes

Not tradable yet (`404`)

Handling `402`

​Status codes

​Not tradable yet (404)

​Handling 402

Status codes

Not tradable yet (`404`)

Handling `402`