duplicate_grant error on repeated OAuth token request

The direct answer

You should expect neither a duplicate_grant error nor reuse of the previously issued token as guaranteed behavior. RFC 6749 defines no idempotency requirement for the token endpoint, and duplicate_grant is not a registered error code — it exists only as a vendor-specific extension in some products. Whether a server returns it, mints a fresh token, or rejects the retry depends entirely on the implementation and the grant type. The only mechanism that guarantees idempotent token acquisition without relying on server behavior is a client-side token cache keyed by grant parameters plus single-flight locking.

What actually happens, by grant type

The likely explanation for a duplicate_grant response, where it exists, is that the server keeps a short-lived record of processed grant parameters and matches identical retries against it. This is per-implementation, usually time-boxed, and absent from most deployments — do not code against it.

• client_credentials: Most servers mint a fresh access token on every request. An identical retry typically produces a second, concurrently valid token rather than reusing the first. A retry here is low risk — worst case, an extra token — though some servers cap tokens per client or revoke older ones, so accumulated duplicates can break running services.
• authorization_code: The code is single-use per RFC 6749 Section 4.1.2. A retry after a timeout usually returns invalid_grant, and the spec says the server SHOULD revoke tokens already issued on that code. A blind retry can destroy the token your first request actually obtained.
• refresh_token: With rotation enabled, a retry can invalidate the newly issued refresh token. Treat ambiguous timeouts here like authorization-code retries.

The Idempotency-Key header is not part of RFC 6749; most servers ignore unknown headers, so it provides no guarantee.

The client-side pattern that works everywhere

1. Build a cache key from the grant parameters: client ID, grant type, scopes, and resource/audience.
2. Before requesting, check the cache. Reuse the token until shortly before expiry (a margin of 30–60 seconds avoids both premature refetches and 401 loops).
3. On a miss, take a per-key lock (single-flight) so concurrent retries collapse into one in-flight request; waiters receive the result of that request.
4. If you run multiple processes, use a shared store (e.g., Redis) — per-process caches each fetch their own token.

// Pseudocode: single-flight cached token acquisition
async function getToken(key, fetchFn) {
  const cached = cache.get(key);
  if (cached && cached.expiresAt > Date.now() + 60_000) return cached.token;
  return locks.acquire(key, async () => {   // concurrent callers wait here
    const again = cache.get(key);            // re-check inside the lock
    if (again && again.expiresAt > Date.now() + 60_000) return again.token;
    const tok = await fetchFn();             // one HTTP request per key
    cache.set(key, tok);
    return tok.token;
  });
}

Handling an ambiguous timeout

For client_credentials, a single retry through the cache/lock path is safe. For authorization_code, do not retry the same code: persist redemption state before sending the request, and on invalid_grant restart the authorization flow instead of reusing the consumed code.

Verify against your server

Because behavior is vendor- and version-specific, confirm it directly:

# Send the identical request twice and compare status, error, and token values
curl -s -X POST https://auth.example.com/token \
  -d 'grant_type=client_credentials&client_id=ID&client_secret=SECRET&scope=read'

To simulate the real failure, route the request through a proxy that drops the response after the server processes it, then retry and observe. Also check your server's documentation or logs for its code-reuse and revocation behavior.

One detail changes this recommendation: which grant type you are retrying, and which server product. Code-based grants need restart-on-invalid_grant handling; client_credentials needs only caching and single-flight.