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

# Error codes and error handling for the 8bitedge API

> Every 8bitedge API error follows a consistent JSON envelope. Learn all 12 error codes, see example responses, and build a reliable retry strategy.

Every error response from the 8bitedge API uses the same JSON envelope, regardless of the cause. Understanding this structure — and knowing what each error code means — lets you build resilient integrations that handle failures gracefully, distinguish between problems you can retry and problems you need to fix, and provide your users with meaningful feedback.

## Error envelope

All errors return a top-level `error` object with the following fields:

```json theme={null}
{
  "error": {
    "code": "string_code",
    "message": "Human-readable message.",
    "details": { ... }
  }
}
```

<ResponseField name="error.code" type="string">
  A stable, machine-readable string that identifies the error type. Use this field in your code to branch on specific failure conditions — never parse `message` programmatically.
</ResponseField>

<ResponseField name="error.message" type="string">
  A human-readable description of the error. Suitable for logging or surfacing to developers, but not intended for end-user display.
</ResponseField>

<ResponseField name="error.details" type="object">
  Optional. Provides context-specific information about the error — for example, which scope is missing, which rate window was exceeded, or how many batch items were received vs. allowed. The shape of `details` varies by error code.
</ResponseField>

## Error codes reference

| Status | `code`                  | Meaning                                             |
| ------ | ----------------------- | --------------------------------------------------- |
| 401    | `unauthorized`          | Missing, invalid, revoked, or expired API key       |
| 403    | `account_inactive`      | Your organization or API client is not active       |
| 403    | `insufficient_scope`    | Your key lacks the required scope for this endpoint |
| 402    | `quota_exceeded`        | Monthly quota exhausted on your plan                |
| 404    | `not_found`             | The requested resource does not exist               |
| 409    | `idempotency_conflict`  | Same idempotency key is still being processed       |
| 422    | `validation_failed`     | Request body failed validation                      |
| 422    | `batch_too_large`       | Batch exceeds your plan's `max_batch_size`          |
| 422    | `idempotency_key_reuse` | Idempotency key reused with a different payload     |
| 429    | `rate_limit_exceeded`   | Per-minute or per-day limit exceeded                |
| 501    | `not_implemented`       | Endpoint exists but logic is not yet available      |
| 500    | `server_error`          | Unexpected server-side error                        |

## Per-error examples

The following examples show the exact response shape for the most common errors you are likely to encounter.

### `unauthorized` — missing or invalid API key

Returned when you make a request without an `Authorization` header, or with a key that is invalid, revoked, or expired:

```json theme={null}
{ "error": { "code": "unauthorized", "message": "Missing API key." } }
```

Ensure your request includes the `Authorization: Bearer <token>` header with a valid, active key.

### `insufficient_scope` — key missing a required scope

Returned when your API key does not carry the scope required by the endpoint you are calling. The `details.required_scope` field tells you exactly which scope to add:

```json theme={null}
{
  "error": {
    "code": "insufficient_scope",
    "message": "This API key is missing the required scope: games.read.",
    "details": { "required_scope": "games.read" }
  }
}
```

Issue a new API key with the appropriate scope, or contact your organization administrator.

### `rate_limit_exceeded` — per-minute or per-day limit hit

Returned when you exhaust your plan's request rate limit. The `details.window` field indicates whether the per-minute or per-day window was hit, and `details.limit` shows the threshold:

```json theme={null}
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded for the minute window.",
    "details": {
      "window": "minute",
      "limit": 120
    }
  }
}
```

Respect the `Retry-After` response header — it tells you exactly how many seconds to wait before retrying. See [Plans & Limits](/concepts/plans-and-limits) for rate limit details by plan.

### `quota_exceeded` — monthly quota exhausted

Returned when your plan's monthly request quota has been fully consumed. No further requests are processed until the quota resets at the start of your next billing period:

```json theme={null}
{
  "error": {
    "code": "quota_exceeded",
    "message": "Monthly quota exhausted. Upgrade your plan or wait for your quota to reset."
  }
}
```

Check `GET /api/v1/me` to see how much quota you have used and when it resets. Consider upgrading your plan if you consistently reach this limit.

### `batch_too_large` — batch exceeds plan maximum

Returned when the number of items in a batch request exceeds your plan's `max_batch_size`. The `details` object tells you both the maximum allowed and how many you submitted:

```json theme={null}
{
  "error": {
    "code": "batch_too_large",
    "message": "The batch exceeds the maximum allowed size for your plan.",
    "details": {
      "max_items": 50,
      "received": 75
    }
  }
}
```

Split your batch into multiple smaller requests, each within the `max_items` limit for your plan.

## Correlation IDs

Every response from the 8bitedge API — both successful responses and errors — includes an `X-Request-Id` header containing a UUID:

```
X-Request-Id: 5f3c1e2a-9d4b-4f87-b3e1-7a02c5d09b21
```

This ID uniquely identifies the request in the API's server-side logs. When you report an issue or open a support ticket, always include the `X-Request-Id` value from the response. It allows the 8bitedge team to look up the exact request, trace its execution path, and diagnose the problem quickly.

<Tip>
  **Retry strategy:** Retry `429` errors after the number of seconds specified in the `Retry-After` header — the server calculates the exact wait time for you. Retry `5xx` errors with exponential backoff and jitter, since they indicate transient server-side problems. Do **not** automatically retry `4xx` errors (other than `409`) — they indicate a client-side problem with your request that will not resolve on its own. For `409 idempotency_conflict`, wait a few seconds and retry; the original request is still in progress and the stored response will be available shortly.
</Tip>