Errors

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.
`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). 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.
`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.

429 is an infrastructure rate limit, 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 page along with the 512 KB request body limit.

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.

Troubleshooting

Symptom-to-fix for snippet, webhook, signature, and scoring issues.

FAQ

Short answers on keys, identifications, identifiers, and a Risk Score of 0.

Rate limits

The infra limits behind 429 and 503, and why they never affect the Risk Score.

Getting started

Web

Server

Core concepts

Detection

Analytics dashboard

Frontend

Backend

Billing and usage

Security and privacy

Troubleshooting

Resources

Support

Legal

HTTP status codes

Snippet results

Troubleshooting

FAQ

Rate limits

Webhooks

​HTTP status codes

​Snippet results

​Related

Troubleshooting

FAQ

Rate limits

Webhooks

HTTP status codes

Snippet results

Related