Skip to main content

​
Errors

Errors use Content-Type: application/problem+json (RFC 9457), with title, status and detail. Branch on the status code, not the message text. 401 responses include OAuth discovery details. The OAuth token endpoints return standard OAuth error JSON instead of problem details.

​
Rate limits

Each connection has a request limit. The token and revocation endpoints have extra abuse limits. 429 responses include Retry-After. Back off exponentially, with jitter, and wait at least that long.

​
Retrying writes

If you resend a write after a timeout, you may create a second task or reminder, or run a scheduled task twice. If you aren’t sure a write went through, read the current state first. If you still can’t tell, stop and tell the user. Save the IDs you get back so you can check later. Don’t retry a token refresh with the same refresh token. Reusing one revokes the connection, so only run one refresh at a time and save the new token straight away.

​
Actions that finish later

When you approve an action, the response shows its state at that moment. The email or update may not have happened yet. Follow it with get_pending_action, and handle failures. See tasks and approvals.