API
Errors & limits
Stable codes, 120 requests a minute, Retry-After on 429.
Errors come back as { error, code }. The HTTP status tells you whether to retry; the code tells you why.
{
"error": "This key is read-only. Turn write on in Settings → API.",
"code": "read_only"
}Status codes
| Status | Code | What it means |
|---|---|---|
| 401 | unauthorized | Missing or invalid token. Send Authorization: Bearer tb_cus_… from Settings → API. |
| 403 | no_subscription | This shop is not on a plan that can use the API. Start Toolbench Core, then retry. |
| 403 | read_only | This key cannot write. Turn write on in Settings → API. ChatGPT stays in preview until you confirm there. |
| 404 | not_found | The record is missing or belongs to another shop. Use an id from GET /contacts, GET /reviews, or GET /actions. |
| 422 | invalid | The body or query did not match the contract. Check the reference for that path. Issues, if present, name the field. |
| 422 | no_number | This shop has no Toolbench number yet. Finish texting setup in the dashboard, then send again. |
| 422 | texting_inactive | Texting is not active on this shop. Carrier registration has to finish before a text can leave. |
| 429 | rate_limited | Too many requests in a minute. Wait for Retry-After (seconds) and retry. Cap is 120 per minute per token. |
Rate limits
| Scope | Limit | Note |
|---|---|---|
| All /api/v1 calls | 120 / minute | Counted per token. 429 includes Retry-After. |
| List pages | limit 1–100 | Default 25. No cursor. Request the next page by changing filters, not by paging tokens. |
A 429 includes Retry-After in seconds. Retry 429 and 5xx. Never retry 400, 401, 403, or 422.