> ## Documentation Index
> Fetch the complete documentation index at: https://docs.0xinsider.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> How errors come back, what each code means, and how to recover.

Errors come back with a non-2xx HTTP status and the same JSON envelope every time:

```json theme={null}
{
  "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

| HTTP  | `error.code`            | What happened                                   | What to do                                                              |
| ----- | ----------------------- | ----------------------------------------------- | ----------------------------------------------------------------------- |
| `400` | `bad_request`           | A parameter was invalid. Check `error.param`.   | 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](https://0xinsider.com/pricing).                  |
| `403` | `forbidden`             | The account was deleted.                        | Contact support.                                                        |
| `404` | `not_found`             | The trader / market / resource does not exist.  | Verify the ID.                                                          |
| `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](/rate-limits). |
| `500` | `internal_error`        | Bug on our side.                                | Retry. Include `meta.request_id` if you contact us.                     |

## Handling errors in code

<CodeGroup>
  ```javascript JavaScript theme={null}
  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;
  }
  ```

  ```python Python theme={null}
  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)
      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("Insider subscription required")
      raise RuntimeError(f"{code}: {body['error']['message']}")
  ```
</CodeGroup>

## 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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="402 subscription_required">
    The key is fine; billing is not. Re-subscribe at [pricing](https://0xinsider.com/pricing) and the same key resumes.
  </Accordion>

  <Accordion title="429 rate_limited">
    Sleep `Retry-After` seconds, then retry. See the backoff example in [Rate Limits](/rate-limits).
  </Accordion>

  <Accordion title="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`](/api-reference/endpoint/search-markets).
  </Accordion>

  <Accordion title="500 internal_error">
    Retry once. If it persists, email [support@0xinsider.com](mailto:support@0xinsider.com) with the `meta.request_id` from the response.
  </Accordion>
</AccordionGroup>