Errors

Handler and middleware errors use the JSON envelope below. The transport-level 408 Request Timeout is the exception: the server’s 30-second timeout returns an empty body, so check the HTTP status before parsing JSON.

{
  "object": "error",
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid or missing API key.",
    "doc_url": "https://docs.0xinsider.com/authentication",
    "param": null
  },
  "meta": {
    "request_id": "req_550e8400"
  }
}

For JSON errors, two fields matter in production: error.code (machine-readable) and meta.request_id (the ID you give us when you contact support).

Error codes

HTTP	`error.code`	What happened	What to do
`400`	`bad_request`	A parameter was invalid. Check `error.param` when present; otherwise use `error.message`.	Fix the input.
`401`	`invalid_api_key`	Key missing, malformed, or revoked.	Re-check the `Authorization` header.
`402`	`subscription_required`	Key is valid, but no active Insider sub.	Subscribe at pricing.
`403`	`forbidden`	The account was deleted.	Contact support.
`404`	`not_found`	The trader / market / resource does not exist.	Verify the ID.
`408`	-	The public API request exceeded the 30-second transport timeout. The body is empty.	Retry once. Do not attempt to parse JSON.
`423`	`account_locked`	Account is suspended.	Contact support.
`429`	`rate_limited`	Over 100 req/min (or 100 batch item units/min).	Sleep `Retry-After` seconds and retry. See Rate Limits.
`500`	`internal_error`	Bug on our side.	Retry. Include `meta.request_id` if you contact us.
`503`	`rate_limit_unavailable`	With `error.reason="read_model_warming"`, this endpoint cannot serve its read model yet. The exact cause is endpoint-specific. Without a reason, the authenticated rate limiter is unavailable and has failed closed.	Branch on `error.reason`. For read-model unavailability, retry only this route after `Retry-After` and consult its endpoint contract. Do not infer dependency health or apply a shared rate-limit backoff.

Handling errors in code

async function call(path, opts = {}) {
  const res = await fetch(`https://api.0xinsider.com/api/v1${path}`, {
    headers: { Authorization: `Bearer ${process.env.OXINSIDER_API_KEY}` },
    ...opts,
  });
  if (res.status === 408) {
    throw new Error("0xinsider request exceeded the 30-second transport timeout");
  }
  const body = await res.json();

  if (!res.ok) {
    const { code, message, param } = body.error;
    if (code === "rate_limited") {
      const wait = Number(res.headers.get("retry-after") ?? 1) * 1000;
      await new Promise(r => setTimeout(r, wait));
      return call(path, opts);
    }
    if (code === "subscription_required") {
      throw new Error("Pro subscription required");
    }
    throw new Error(`${code}: ${message}${param ? ` (param=${param})` : ""}`);
  }

  return body;
}

import os, time, requests

BASE = "https://api.0xinsider.com/api/v1"
H = {"Authorization": f"Bearer {os.environ['OXINSIDER_API_KEY']}"}

def call(path, **params):
    r = requests.get(f"{BASE}{path}", headers=H, params=params)
    if r.status_code == 408:
        raise TimeoutError("0xinsider request exceeded the 30-second transport timeout")
    body = r.json()
    if r.ok:
        return body

    code = body["error"]["code"]
    if code == "rate_limited":
        time.sleep(int(r.headers.get("Retry-After", "1")))
        return call(path, **params)
    if code == "subscription_required":
        raise RuntimeError("Pro subscription required")
    raise RuntimeError(f"{code}: {body['error']['message']}")

Per-item batch errors

Batch endpoints (e.g. POST /api/v1/traders/batch) return 200 OK even when individual items fail. Each item carries its own error field. Read data[i].error per item, not just the top-level status.

Quick troubleshooting

401 invalid_api_key

The header needs Authorization: Bearer oxi_sk_live_....
The key is 76 characters. Confirm you copied the full string.
If you regenerated, the old key is dead. Update every consumer.

402 subscription_required

The key is fine; billing is not. Re-subscribe at pricing and the same key resumes.

429 rate_limited

Sleep Retry-After seconds, then retry. See the backoff example in Rate Limits.

400 bad_request on Market Intel with a prefixed ID

Market Intel takes the raw condition_id or the mkt_... market ID from V1 responses. It rejects non-market prefixes (trd_, wt_, rf_) with 400 bad_request. If you only have one of those, resolve the market first via /markets/search.

500 internal_error

Retry once. If it persists, email support@0xinsider.com with the meta.request_id from the response.

Getting Started

Guides

Concepts

Error codes

Handling errors in code

Per-item batch errors

Quick troubleshooting

​Error codes

​Handling errors in code

​Per-item batch errors

​Quick troubleshooting

Error codes

Handling errors in code

Per-item batch errors

Quick troubleshooting