Errors
Stable HTTP status codes + machine-readable error codes in the
JSON body. Switch on the error field, not on
English strings — the prose is for humans, the code is the
contract.
Response shape
{
"error": "stable_machine_code",
"message": "Free-form human diagnostic. Do not parse."
}HTTP status codes you should expect
| Status | Class | What it means |
|---|---|---|
200 | Success | Request succeeded; body has the payload. |
400 | Client | Body or query string is malformed. |
401 | Auth | Missing, invalid, revoked, or expired bearer token. |
402 | Payment | Payment required. Body carries the challenge. |
403 | Auth | Token is valid but doesn't own the resource you're touching. |
404 | Client | Path or referenced ID doesn't exist. |
409 | Conflict | State conflict (e.g. number already on a call). |
500 | Server | Internal error. Retry transparently — usually transient. |
502 | Server | Hardware-side error. Retry. |
503 | Server | Capacity issue (pool exhausted, hardware busy). Retry with backoff. |
Common error codes
| Code | HTTP | Where |
|---|---|---|
invalid_request | 400 | Body / query missing required fields |
unauthorized | 401 | Bearer missing or invalid |
signature_mismatch | 401 | Auth recovery: signature didn't recover the claimed wallet |
nonce_invalid | 401 | Auth recovery: nonce expired, used, or unknown |
no_active_subscription | 402 | Wallet has no active subscription |
pool_exhausted | 503 | No phone numbers currently free |
phone_node_error | 502 | Upstream hardware unreachable |