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

# Errors

> Every HTTP status code ShieldLabs returns, by API, and what to do.

Error bodies differ by surface, so branch on the HTTP status code, not on a body field.

* **Identification request** (`rest.shieldlabs.ai`, sent by the snippet): an empty body for `400`, `401`, `402` and `409`; `{ "error": "..." }` for `429` and `503`.
* **History API** (`account.shieldlabs.ai`): `{ "error": "..." }` for `401`, `429` and `500`.
* **Management API** (`api.shieldlabs.ai`): an empty body for `401`; `{ "error": "..." }` for `429` and `503`; on the deprecated history path only, a bare JSON string for `400` and `404`.

## HTTP status codes

| Status | Meaning | What to do |
| - | - | - |
| `200` | Success | Parse the response. |
| `400` | Bad request | Identification request: a malformed, stale or replayed payload (empty body); the snippet handles it. Management API history (deprecated): a malformed value, such as a non-UUID where a UUID is required (bare JSON string). Fix the request. |
| `401` | Bad credentials or a paused domain | Identification request: the public key does not match the domain, or the domain is **Paused** under **Integration > Domains** in the analytics dashboard (empty body). History API: a missing or invalid `Authorization: Bearer` key, or a **Paused** domain (`{ "error": "..." }`). Management API: a bad `X-Shield-Domain` or `Authorization: Bearer` secret (empty body). See [API keys](/setup/keys). |
| `402` | Included volume used up | Identification request only, empty body. Your account has used its included volume; identification resumes when the billing cycle resets or you change plan ([billing](/billing)). History API and profile reads never return `402`. |
| `404` | Unsupported history `type` | Management API history (deprecated) only, bare JSON string. On the History API, use one of the seven types (`user_hid`, `device_id`, `visitor_id`, `ip`, `request_id`, `session_id`, `cookie_id`): an unknown type is not rejected and returns the domain's latest rows unfiltered. A supported type that matches nothing returns `200` with an empty list. |
| `409` | Request already processed | Identification request only, empty body: this request ID was already scored, so the request is a replay. Nothing is counted. |
| `429` | Rate-limited | Identification request and network check: per IP, per domain, or domain freeze. Management API: 15 requests per minute per IP, then a 10-minute ban. History API: 15 requests per second per domain. Body `{ "error": "too many requests" }`. Back off and retry; see [rate limits](/rate-limits). |
| `500` | Internal error | Transient. Retry with backoff. |
| `503` | Server busy | Identification request, network check and Management API: 512 requests in flight at once. Body `{ "error": "server is busy" }`. Retry with backoff. |

<Warning>
  `429` is an **infrastructure [rate limit](/rate-limits)**, separate from the Risk Score: it protects the gateway and never feeds the Risk Score. The Risk Score is 0 to 100; the only exception is the `999` ban marker, explained on the [rate limits](/rate-limits) page along with the 512 KB request body limit.
</Warning>

## Snippet results

The snippet methods return nothing and never throw. `onInitialized` receives `{ status: "initialized", requestID }` when an identification starts, or `{ status: "not_initialized" }` when none runs: a call within five minutes of the last identification for the same user in the same visit, an identification for that user already in progress, a malformed public key in the snippet URL, or an internal error. A call that does not run posts nothing and counts nothing.

## Related

<CardGroup cols={2}>
  <Card title="Troubleshooting" icon="wrench" href="/troubleshooting">
    Symptom-to-fix for snippet, webhook, signature, and scoring issues.
  </Card>

  <Card title="FAQ" icon="circle-question" href="/faq">
    Short answers on keys, identifications, identifiers, and a Risk Score of 0.
  </Card>

  <Card title="Rate limits" icon="gauge-high" href="/rate-limits">
    The infra limits behind `429` and `503`, and why they never affect the Risk Score.
  </Card>

  <Card title="Webhooks" icon="bolt" href="/setup/webhooks">
    Register, receive, and verify webhooks, with the no-retry delivery model.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.