◆Error Codes Wiki

OAuth2 invalid_grant Error — Token Refresh and Authorization Code Failures

Error4xx client error

Overview

Fix OAuth2 invalid_grant error responses when exchanging authorization codes or refreshing access tokens fails due to expired, revoked, or misused credentials.

Key Details

  • The invalid_grant error is returned when an authorization grant (code or refresh token) is invalid or expired
  • Authorization codes are single-use and typically expire within 10 minutes of issuance
  • Refresh tokens can be revoked by the user, expired by the server, or invalidated by password changes
  • This is one of the most common OAuth2 errors in production applications
  • Google, Microsoft, and other providers may revoke refresh tokens after 6 months of inactivity

Common Causes

  • Authorization code used more than once (codes are single-use by spec)
  • Authorization code expired before being exchanged for tokens (typically 10-minute window)
  • Refresh token revoked by user changing password or revoking app access
  • Redirect URI in token exchange does not exactly match the one used in authorization request

Steps

  1. 1Ensure authorization codes are exchanged immediately and only once — never store or reuse them
  2. 2Implement automatic re-authorization flow when refresh token is rejected with invalid_grant
  3. 3Verify the redirect_uri parameter exactly matches between authorization and token exchange requests
  4. 4Store refresh tokens securely and implement token rotation when the provider supports it
  5. 5Handle the error gracefully in your UI — redirect users to re-authenticate with a clear message

Tags

oauth2invalid-granttokenrefreshauthentication

More in 4xx Client Error

http-400-bad-requestHTTP 400 Bad Request — What It Means & How to Fix It
Error
http-401-unauthorizedHTTP 401 Unauthorized — What It Means & How to Fix It
Error
http-402-payment-requiredHTTP 402 Payment Required — What It Means & How to Fix It
Error
http-403-forbiddenHTTP 403 Forbidden — What It Means & How to Fix It
Error
http-404-not-foundHTTP 404 Not Found — What It Means & How to Fix It
Error
http-405-method-not-allowedHTTP 405 Method Not Allowed — What It Means & How to Fix It
Error

Frequently Asked Questions

Providers revoke refresh tokens when: the user changes their password, the user revokes app access, the token has not been used for an extended period (6 months for Google), or the app's client secret has changed.