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:

{ "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 ([phone], 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.