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:Status codes
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 anIdempotency-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.