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 400, 401, 429 and 500.
Management API (api.shieldlabs.ai): an empty body for 401; { "error": "..." } for 429 and 503.

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. History API: unsupported search type, invalid path value, or invalid/repeated pagination parameters (`invalid_request`). 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`	Endpoint not found	Check the host and path. History searches with a supported type and no matches return `200` with an empty list.
`409`	Conflicting request	Identification admission rejects a reused Identification ID with a different payload. An identical admitted payload is idempotent and does not debit the quota again.
`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 separate value 999 means Banned IP, explained on the rate limits page along with the 512 KB request body limit.

Snippet results

The snippet reports initialization through callbacks. Handle import and application errors separately. onInitialized reports status: "initialized" with an Identification ID when a check 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

Account and domains

Browser integration

Server integration

AI

Billing and usage

Troubleshooting

Help

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