Errors & limits
One error format, a trace id on everything, and how rate limits answer.
Error format
Errors are RFC 9457 application/problem+json:
{
"type": "about:blank",
"title": "Bad Request",
"status": 400,
"detail": "length must be between 4 and 8",
"trace_id": "01JB2K…"
}trace_id is also in the X-Request-ID header. Paste it into the console's
audit or verification search to see the full request, provider attempts
included.
| Status | Means | Do |
|---|---|---|
400 | Invalid input, or wrong/expired code | Fix the request / ask for a new code |
401 | Missing or unknown API key | Check x-api-key |
403 | Key lacks the scope, or the firewall blocked it | Check key scopes and firewall rules |
429 | Rate or send limit | Wait Retry-After seconds |
5xx | Our side, or every provider failed | Retry with backoff; quote the trace_id |
Rate limits
- Per business: set a budget in Console → Testing & limits
(count per window, per target and IP).
0means unlimited. - Send limits: firewall caps per destination, IP, channel, prefix or carrier. All-or-nothing — a refused send spends no budget.
- Per key: a throttle on every API key.
A limited request answers 429 with Retry-After. Don't retry sooner.