Errors and retries

The API returns JSON errors with a machine-readable error.code. Check the HTTP status first: 400 means invalid input, 401 means missing or invalid credentials, 403 means the token lacks permission, 404 means the route or resource is unavailable, 409 means a revision or confirmation conflict, and 429 means a rate limit.

For a 429 response, wait for Retry-After before trying again. Give writes an Idempotency-Key when the operation requires it. Do not retry a non-idempotent write with a new key after an uncertain result until you have checked its state.