Errors and rate limits

Status codes

Code	Meaning	What to do
`200`	Success.	—
`400`	The request body or query is invalid.	Read `error` in the response; fix the field it names.
`401`	Missing, malformed, or revoked credentials.	Check the `Authorization` header; rotate the key if needed.
`403`	Authenticated, but not allowed for this firm or role.	Confirm the `firmSlug` matches your key.
`404`	No such record for this firm.	Verify the ID — IDs are scoped per firm.
`429`	Too many requests, or a calling limit was reached.	Back off and retry; see calling limits below.
`503`	A dependency (auth store, telephony, CRM) is unavailable.	Retry with backoff. Call-placing paths fail closed rather than dial.

Errors return JSON with a human-readable message:

{ "error": "That number is on the firm's Do Not Call list." }

Calling limits

Outbound calling is deliberately conservative — your firm’s number is the thing being protected.

50 calls per firm per day

The counter resets at UTC midnight. The 51st call is refused before dialing.

One call per number every two hours

A repeat within the window is refused, so a retry loop cannot pester a client.

9:00 a.m. to 8:00 p.m. in the recipient's time zone

The window is derived from the recipient’s area code. If the zone cannot be determined, the call is refused rather than guessed.

Do Not Call is absolute

Numbers on the firm’s DNC list are never dialed, and the check fails closed if the list cannot be read.

High call volume can get a number labeled as spam by carriers, which no API limit can undo. Spread campaigns out.

Status codes