Errors, limits & safe retries
Understand HTTP failures and avoid repeating consequential operations.
On this page
REST response format
Successful tool requests return a JSON object with tool and result. Errors return { error: "message" }. Results differ by tool; do not assume a single universal rows array. All tool responses use Cache-Control: no-store.
| Status | Meaning / next action |
|---|---|
| 400 | Invalid JSON, invalid arguments, missing projectId or invalid custom dates; fix inputs |
| 401 | Missing, invalid, expired or revoked credential; authenticate again |
| 403 | Project, membership, role or write permission denied; review access |
| 404 | Unknown tool or missing authorized record; check the tool/record identifier |
| 405 | Mutation attempted with GET; use POST with write consent |
| 413 | Request body exceeds the route's accepted size |
| 429 | A throttled operation exceeded its allowed rate; wait before retrying |
| 502 | An external operation such as provider or email delivery failed |
| 500 | Tool execution failed; retry reads with bounded backoff and investigate |
Schema limits
There is no single universal pagination contract: some tools use limit/offset, private chats use cursors, and some reports are aggregates. Every tool page lists required arguments and the full JSON schema with bounds and defaults. Use POST for nested filter objects.
Rate limits
The shared authenticated HTTP context permits up to 600 requests per minute per API key or OAuth grant. Sensitive operations have additional per-user throttles, including invitations, sync, DNS verification and privacy requests. Inspect errors and avoid polling detailed reports at high frequency; realtime and historical tools serve different purposes.
Retry safely
Reads can usually be retried with bounded exponential backoff. Do not assume a failed network response means a write did not happen. Re-read the affected record or audit status before retrying create, invitation, webhook registration, deletion or erasure operations. Not every write has a client-supplied idempotency key.
Keep diagnostics clean
Report the tool name, status, approximate time and sanitized error. API activity intentionally omits arguments and secrets. Never include bearer tokens or provider keys in a support message.
Still looking for an answer? Try troubleshooting or get in touch.