Concepts
Errors
Every error is a stable machine-readable code. REST uses the same codes as MCP.
| Code | HTTP | Meaning | Fix |
|---|---|---|---|
invalid_request | 400 | Malformed or missing required arguments. | Fix the payload. Retrying the same body will fail identically. |
unauthorized | 401 | Missing, expired, or invalid API key or OAuth token. | Check the Authorization header. Keys are shown once at creation. |
insufficient_scope | 403 | The key is missing a required permission. | Grant the scope in Settings, or use a key that has it. No rotation needed. |
tier_locked | 403 | The account is not on Growth. | Relay the returned upgrade_url and stop. Do not retry. |
not_found | 404 | The business, prompt, or recommendation ID does not exist on this account. | Re-read list_businesses — IDs are per account. |
rate_limited | 429 | Too many requests. | Respect retry_after in seconds before retrying. |
quota_exceeded | 402 | The account's check pool is exhausted. | Do not retry and do not split the action into smaller calls. |
over_committed | 402 | Tracked prompts already exceed the plan pool. | Offer to reduce cadence or untrack prompts. |
internal_error | 500 | Unexpected server error. | Safe to retry once. |
Rate limits
- Read tools: 60 requests / 60 seconds (per authenticated user)
- Action tools: 10 requests / 60 seconds, 500 / day (per authenticated user)
- Anonymous readiness check: 5 requests / 24 hours (per source IP)
A rate_limited response includes retry_after in seconds. Wrong method returns 405. Unknown tools return 404.