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

# Errors and limits

> The error envelope, rate limits, credits, and idempotency.

## Error envelope

Every error is the same shape, and validation reports the **full violation set in one pass** — fix everything at once, not one field per retry:

```json theme={null}
{ "errors": [ { "code": "E_PHONE_INVALID_E164", "field": "subject.phone_number", "message": "phone number is not valid E.164" } ] }
```

## Status codes

| Status | Code                   | Meaning                                      | What to do                                                                                    |
| ------ | ---------------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------- |
| 422    | `E_*` validation codes | Bad request shape or values                  | Fix and resend                                                                                |
| 401    | `E_AUTH_INVALID`       | Missing, unknown, or revoked key             | Check the key                                                                                 |
| 429    | `E_RATE_LIMITED`       | Your organisation's per-second rate exceeded | Wait `Retry-After` seconds. `X-RateLimit-Limit` / `X-RateLimit-Remaining` describe the window |
| 402    | `E_CREDITS_EXHAUSTED`  | Credit allowance for the period exhausted    | Top up, or contact FIL                                                                        |
| 409    | conflict codes         | Idempotency replay mismatch                  | See idempotency below                                                                         |

Rejected requests are never scored and never billed. 429 means wait a moment; 402 means the account needs attention — they're deliberately distinct signals.

## Rate limits and credits

Both are per organisation — all your keys share one budget. Your tier sets the request rate; your plan sets the monthly credit allowance, and each scored request consumes credits. Live usage is on the portal's **Usage** page.

## Idempotency

Send an `Idempotency-Key` header to make retries safe: the same key returns the original stored response instead of scoring (and billing) twice. Reusing a key with a *different* request body is a 409.

## Number formatting

E.164, digits only after `+`, **no national trunk zero** (`+443444930787`, never `+44 (0)344…`). A trunk-zero number passes validation but resolves to no numbering range — it scores as unattested, with no operator attribution in the `subject` block. If your responses are missing operator data, check your formatting first.