> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whirl.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors and retries

> Status codes, rate limits, and how to retry without repeating a write.

## Errors

Errors use `Content-Type: application/problem+json` ([RFC 9457](https://www.rfc-editor.org/rfc/rfc9457)), with `title`, `status` and `detail`. Branch on the status code, not the message text.

| Status | What to do |
| - | - |
| 400 | Fix the arguments, URL encoding or JSON. Retrying the same request won't help. |
| 401 | Refresh the token, or ask the user to reconnect. |
| 403 | The token is missing a scope, or the user doesn't have permission. |
| 404 | Check the ID. Whirl also returns 404 for things the user can't access. |
| 409 | Re-read the current state and resolve the conflict before trying again. |
| 429 | Wait for the time in `Retry-After`. |
| 5xx or timeout | Check whether a write went through before you retry. |

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](/workflows).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.