Errors and rate limits
Errors and status codes
| Status | Code | Meaning |
|---|---|---|
400 | VALIDATION_ERROR (including a user.phone with no digit), CARD_NUMBER_DETECTED, NUL_CHARACTER_DETECTED | Invalid body. parameter names the field. |
401 | AUTH_ERROR | Missing or invalid key. |
403 | SCOPE_ERROR, SANDBOX_KEY_FORBIDDEN, ACCOUNT_SHARED_ACROSS_PROJECTS | Key lacks the scope, a sandbox key was used for an operation that needs a live one, or the account spans several projects. |
404 | NOT_FOUND | Unknown event_id, account or case. |
409 | EVENT_ID_CONFLICT | event_id reused with a different body. |
413 | PAYLOAD_TOO_LARGE | Body above the limit. |
429 | RATE_LIMIT_EXCEEDED | See rate limits. |
500 | INTERNAL_ERROR | Scoring failed to persist. Safe to retry the same event_id and body. |
503 | ASYNC_UNAVAILABLE, COMPILED_RULES_UNAVAILABLE, PROJECT_POLICY_UNAVAILABLE, RATE_LIMIT_UNAVAILABLE | Async ingestion, the compiled ruleset (sync only) or the project policy is unavailable, or the rate limiter is not ready. Nothing was scored or stored. Retry with backoff. |
Per-endpoint status lists are in the API reference.
Rate limits
Limits are counted per key, per method and route, in a fixed window (default 1m). Defaults of the service:
| Bucket | Default |
|---|---|
| Per key and route | 1000 requests / window |
POST /v1/fp/collect, per key | 10 000 requests / window |
POST /v1/fp/collect, per key and caller address | 60 requests / window |
| Failed key lookups (a well-formed key that does not exist or is inactive), per caller address | 60 / window |
These are the service defaults; values configured for your deployment may differ. Once the failed-lookup limit is hit, further unknown keys from that address get 429 with Retry-After only. Other 429s carry Retry-After, RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (all in seconds or counts as named); back off for Retry-After seconds.