Errors, limits and idempotency
Handle REST and MCP responses safely.
Errors and limits
The REST API returns JSON errors with error and message fields.
| HTTP status | Interpretation | Suggested action |
|---|---|---|
| 400 | Invalid parameters or missing request ID | Correct request |
| 401 | Invalid, expired, missing or revoked credential | Reauthorize or replace key |
| 403 | Scope or organization/workspace access denied | Reduce scope or change account permission |
| 404 | Unknown endpoint or inaccessible resource | Check route and ID |
| 409 | Conflicting idempotency key or unsafe state | Check thread status before retrying |
| 429 | Developer key rate limit reached | Back off and reduce calls |
| 500 | Unexpected server failure | Retry reads with backoff; investigate writes before retry |
API key limits
The current developer-key implementation limits each key to 60 authenticated requests per minute. Further infrastructure or account-specific limits may be in place. Ask for only the data you need; requests with limit parameters support explicit maximums.
Idempotency for writes
Three REST operations modify data: POST /conversations/watch, POST /drafts, and POST /followups/pause. Every write needs either JSON requestId or the Idempotency-Key header.
Accepted characters: A-Z, a-z, 0-9, _, ., :, -; 8–100 characters.
Reuse a key only to represent the same logical operation with the same arguments. The API rejects using the same key for a different action. A request that is already processing or ended in an uncertain state produces a conflict; check status before deciding to try again.
Safety
A draft is not a sent email. Nudge requires an existing sent conversation for watching and drafting. A mailbox configured for auto-send is not eligible for external watch/draft writes.
Access management
Create/revoke developer keys, set their scope/expiration/workspace and disconnect OAuth clients in Settings → Developer API. Rotate keys and disconnect apps that no longer need access.