Recover an agent connection

A temporary authorization failure does not necessarily mean your agent connection was revoked. The recovery action depends on the token endpoint's HTTP status and OAuth error.

Temporary unavailability

A 503 response with error: "temporarily_unavailable" means the service cannot complete the authorization check right now. No new credentials are returned. A Retry-After: 5 header asks the client to wait at least five seconds before another attempt.

Keep the current refresh token rather than deleting it solely because of this response. Retry with backoff, and avoid simultaneous refresh attempts. A failed connection check before refresh rotation does not consume a live refresh token; after recovery, it can be used without another sign-in or consent prompt, provided the connection remains authorized.

After a successful refresh, store the new refresh token and stop using the previous one. Do not apply this advice to a token that has already been successfully rotated.

Service errors

A 500 response with error: "server_error" indicates a service-side problem. Repeatedly signing in or deleting credentials will not repair it. Stop rapid retries and contact support if the error persists. Share the approximate time, HTTP status and error name, but never share an access token or refresh token.

Refused access

A 400 response with error: "invalid_grant" is a definitive refusal, not an instruction to retry indefinitely. The connection may have been revoked, workspace access may have changed, or the refresh credential may be invalid. Check your access and reconnect through your agent host when appropriate. To see whether the approval is still active, open Agents and keys (/agents) in the Console: each approval shows its status as Active, Pending or Revoked. See Revoke agent access.

Initial connection and lost responses

Authorization codes are single-use. A failure while exchanging a new authorization code does not guarantee that the code can be reused; restarting the connection flow may be necessary. Likewise, a lost network response is not proof that a refresh failed before rotation. Follow your agent host's recovery flow rather than repeatedly replaying an old credential after an uncertain result.