Skip to main content
Errors come back with a non-2xx HTTP status and the same JSON envelope every time: 
{
  "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"
  }
}
Two fields matter in production: error.code (machine-readable) and meta.request_id (the ID you give us when you contact support).

​
Error codes

HTTPerror.codeWhat happenedWhat to do
400bad_requestA parameter was invalid. Check error.param.Fix the input.
401invalid_api_keyKey missing, malformed, or revoked.Re-check the Authorization header.
402subscription_requiredKey is valid, but no active Insider sub.Subscribe at pricing.
403forbiddenThe account was deleted.Contact support.
404not_foundThe trader / market / resource does not exist.Verify the ID.
423account_lockedAccount is suspended.Contact support.
429rate_limitedOver 100 req/min (or 100 batch item units/min).Sleep Retry-After seconds and retry. See Rate Limits.
500internal_errorBug on our side.Retry. Include meta.request_id if you contact us.

​
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,
  });
  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("Insider subscription required");
    }
    throw new Error(`${code}: ${message}${param ? ` (param=${param})` : ""}`);
  }

  return body;
}

​
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

  • 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.
The key is fine; billing is not. Re-subscribe at pricing and the same key resumes.
Sleep Retry-After seconds, then retry. See the backoff example in Rate Limits.
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.
Retry once. If it persists, email support@0xinsider.com with the meta.request_id from the response.