Skip to content

[Doc] Bound the token endpoint error docs to what sets the readers #633

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
koic merged 1 commit into from
Oct 26, 2026
+9 −5
Merged

[Doc] Bound the token endpoint error docs to what sets the readers #633

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 9 additions & 5 deletions docs/_client/authorization.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -268,18 +268,22 @@ so the storage should expire entries older than `pending_authorization_max_age`,

### Token Endpoint Errors

When a token exchange or refresh fails, `MCP::Client::OAuth::Flow::AuthorizationError` includes the HTTP status and
the authorization server's `error` and `error_description` from [RFC 6749 Section 5.2](https://www.rfc-editor.org/rfc/rfc6749#section-5.2).
When the token endpoint answers a token exchange or refresh with a non-2xx response within the body cap,
`MCP::Client::OAuth::Flow::AuthorizationError` includes the HTTP status and the authorization server's `error`
and `error_description` from [RFC 6749 Section 5.2](https://www.rfc-editor.org/rfc/rfc6749#section-5.2).
For example:

```text
Token endpoint returned status 400. invalid_request: Client must not use multiple authentication methods
```

The exception exposes `http_status`, `error`, and `error_description` readers for structured diagnostics. Missing or non-string
diagnostic fields are `nil`; non-JSON responses retain the status-only message. Other authorization failures have `nil` readers.
An `invalid_grant` response still raises `Flow::InvalidGrantError`, a subclass of `Flow::AuthorizationError`, so refresh-token
recovery behavior is unchanged.
diagnostic fields are `nil`, as are blank ones; non-JSON responses retain the status-only message.
When the authorization server returns an error to the authorization callback ([RFC 6749 Section 4.1.2.1](https://www.rfc-editor.org/rfc/rfc6749#section-4.1.2.1)),
`error` and `error_description` are set the same way, with `http_status` left `nil`; other authorization failures have `nil` readers.
A token endpoint response whose raw `error` is exactly `invalid_grant` still raises `Flow::InvalidGrantError`, a subclass of
`Flow::AuthorizationError`, so refresh-token recovery behavior is unchanged. The class follows the raw value
while the `error` reader holds the sanitized one, so `error == "invalid_grant"` alone does not imply that class.

Diagnostic fields are limited to 128 characters for `error` and 512 for `error_description`, including a trailing `...` when
truncated. Characters outside the RFC's printable ASCII set are replaced with spaces, and surrounding whitespace is removed.
Expand Down
Loading