[{"data":1,"prerenderedAt":140},["ShallowReactive",2],{"doc:\u002Freference\u002Ferrors":3},{"page":4,"toc":136,"updated":139},{"path":5,"title":6,"seoTitle":7,"description":8,"blocks":9},"\u002Freference\u002Ferrors","Errors","API Errors: Status Codes and Error Codes","How the Fingerly API reports errors: one JSON error shape, conventional HTTP statuses, and stable error codes you can branch on.",[10,13,20,42,47,124,127,132],{"type":11,"text":12},"p","Errors use conventional HTTP statuses and one JSON body shape. Branch on `error.code`, which is stable; `error.message` is written for people and may change.",{"type":14,"samples":15},"code",[16],{"label":17,"lang":18,"code":19},"422 Unprocessable Entity","json","{\n  \"error\": {\n    \"code\": \"validation_error\",\n    \"message\": \"The request could not be validated.\",\n    \"status\": 422,\n    \"details\": [\n      {\n        \"field\": \"tag\",\n        \"location\": \"body\",\n        \"issue\": \"must be a string\"\n      }\n    ]\n  },\n  \"request_id\": \"01a0a84c-0f11-7a3e-9c2d-4b5e6f708192\"\n}",{"type":21,"title":22,"fields":23},"fields","Error body",[24,28,31,35,39],{"name":25,"type":26,"text":27},"error.code","string","A stable, machine-readable code.",{"name":29,"type":26,"text":30},"error.message","A human-readable explanation.",{"name":32,"type":33,"text":34},"error.status","integer","The HTTP status, repeated.",{"name":36,"type":37,"text":38},"error.details","array","For validation errors: which `field`, where (`body`, `query`, `path`, `header`) and the `issue`. Omitted otherwise.",{"name":40,"type":26,"text":41},"request_id","The request's ID, also in the `X-Request-Id` header.",{"type":43,"level":44,"text":45,"id":46},"heading",2,"Error codes","error-codes",{"type":48,"columns":49,"rows":54},"table",[50,51,52,53],"Status","Code","What happened","What to do",[55,60,65,69,74,79,84,89,94,98,102,106,110,114,119],[56,57,58,59],"`401`","`unauthorized`","The key did not authenticate for this request.","Check the key, its kind, its region and its allowed origins.",[61,62,63,64],"`402`","`billing_blocked`","The organization is not accepting traffic.","Resolve billing in the dashboard.",[61,66,67,68],"`no_credit`","The organization's balance is used up.","Add funds or turn on auto top-up.",[70,71,72,73],"`404`","`event_not_found`","No event with this request ID in the key's environment.","Check the ID and the environment. Events are readable for 30 days.",[75,76,77,78],"`409`","`supplement_conflict`","A different deferred report was already accepted for this request.","Do not retry with different content.",[80,81,82,83],"`413`","`payload_too_large`","The body is over 1 MiB.","Send a smaller body.",[85,86,87,88],"`415`","`unsupported_media_type`","The body is not JSON.","Send `Content-Type: application\u002Fjson`.",[90,91,92,93],"`422`","`validation_error`","The body or parameters are malformed.","Read `error.details`.",[90,95,96,97],"`idempotency_key_too_long`","The `Idempotency-Key` is over 255 characters.","Use a shorter key, such as a UUID.",[90,99,100,101],"`invalid_request_id`","The request ID is not a Fingerly request ID.","Pass the `request_id` exactly as returned.",[90,103,104,105],"`invalid_window`","The time window, page, level or visitor filter is not valid.","See [List events](\u002Freference\u002Flist-events).",[90,107,108,109],"`invalid_supplement`","The deferred report or its token is not valid, or the token expired.","Deferred reports must arrive within 24 hours.",[90,111,112,113],"`invalid_visitor_metadata`","A proxy forwarded a malformed visitor address, origin or user agent.","Fix the proxy's forwarded headers.",[115,116,117,118],"`429`","`rate_limited`","The organization is over its rate limit.","Wait `Retry-After` seconds, then retry.",[120,121,122,123],"`503`","`service_unavailable`","Fingerly could not answer just now.","Retry with backoff and the same `Idempotency-Key`.",{"type":43,"level":44,"text":125,"id":126},"Retrying","retrying",{"type":128,"items":129},"list",[130,131],"**Retry** `429` after `Retry-After`, and `5xx` and network errors with exponential backoff. Reuse the same `Idempotency-Key` so a retried identification is answered and charged once.","**Do not retry** `401`, `402`, `413`, `415` or `422`. They describe the request or the account, not a passing condition.",{"type":133,"tone":134,"text":135},"callout","note","The client SDKs already follow these rules. See [Idempotency and retries](\u002Freference\u002Fidempotency).",[137,138],{"id":46,"text":45,"level":44},{"id":126,"text":125,"level":44},"2026-09-17T08:28:36.000Z",1789667797845]