Skip to main content
Errors return a machine-readable code in a small body:

​
Batch errors — POST /v1/signals

An unknown key anywhere in the request body is a malformed request, not ignored (422).

​
Poll errors — GET /v1/signals/{request_id}

​
Item-level outcomes

An item is never a transport error. Within a 200/202 batch an item can be rejected (no_runnable_signal, invalid_phone, …), error, or unresolved. A per-signal vendor outage degrades that signal to null — it never fails the whole batch. See item outcomes.

​
429 vs 422

Every 429 carries a Retry-After header — whole seconds, always at least 1 — so a refusal always tells you when to come back. A 422 never does. That is the distinction worth coding against: a 429 is “not yet”, a 422 is “not like this”.
A batch larger than the account’s own ceilings is a 422 on inputs rather than a 429, because no amount of waiting would make it fit.

​
Rate limits and batch size

Published numbers are to be finalized. The 429 rate_limited response, its Retry-After header, and the x-limits fields in the OpenAPI spec are documented, but the maximum batch size and per-account rate limit are not yet set.