Errors And Retries
Handle MCP OAuth errors, tool errors, scopes, and safe retries.
Tool errors use the same structured API error shape when they cross the HTTP boundary.
Retry only when the error is retryable.
For paid tools, retry with the same idempotency_key.
Do not retry bad_request, forbidden, payment_required, insufficient_credits, or idempotency conflicts without changing the request or asking the user.
Common OAuth Errors
| Error | Meaning |
|---|---|
invalid_request | Malformed token request or invalid resource. |
invalid_scope | Unsupported scope or a scope outside the registered client scope. |
invalid_grant | Invalid, expired, used, or mismatched auth code, verifier, state, refresh token, or resource. |
unsupported_grant_type | Only authorization_code and refresh_token are supported. |
rate_limited | OAuth registration or token endpoint limit exceeded. |
server_error | Unexpected server failure. |
Scope Failures
If a tool needs additional scopes, the MCP HTTP response includes required scope context.
For social publishing, reconnect with social:read social:write if the connection only has the default generation scopes.