Error Codes Reference

This is the comprehensive reference for all error codes returned by Oten IDP. All other documentation references this central source.

📖 For Troubleshooting: See Common Errors for step-by-step solutions. 📖 For Implementation: See Step 4: Handle Callback for code examples.

🔄 Authorization Endpoint Errors (/v1/oauth/authorize)

Authorization errors are returned as URL parameters in the redirect URI:

HTTP/1.1 302 Found
Location: https://yourapp.com/callback?
  error=invalid_request&
  error_description=The%20request%20is%20missing%20a%20required%20parameter&
  state=xyz789

Standard OAuth 2.0 Errors (RFC 6749)

Error Code	Description	When It Occurs	HTTP Status	Retryable
invalid_request	Missing required parameter or malformed request	• Missing response_type • Missing client_id • Missing redirect_uri • Invalid parameter values	400	No
invalid_client	Client authentication failed	• Client credentials not found • Invalid client credentials during JAR verification	401	No
unauthorized_client	Client not authorized for this method	• Client not authorized for authorization code flow • Public client without PKCE	403	No
unsupported_response_type	Response type not supported	• Unsupported response_type value • Only code is supported	400	No
invalid_scope	Requested scope invalid	• Invalid scope values • Scope not supported by client	400	No
access_denied	User denied authorization	• User clicked "Deny" on consent screen • User cancelled authentication	400	Yes
server_error	Internal server error	• Database connection failures • Token generation failures	500	Yes
temporarily_unavailable	Service temporarily unavailable	• Server maintenance • High load conditions	503	Yes

JAR-Specific Errors (RFC 9101)

Error Code	Description	When It Occurs	HTTP Status	Retryable
invalid_request_object	Invalid JAR token	• JWT parsing failed • Invalid JWT signature • Unsupported signing method • Malformed JWT structure	400	No
request_not_supported	JAR not supported	• Server doesn't support JAR • JAR disabled in configuration	400	No

Oten Specific Error Scenarios

Oten IDP uses standard OAuth 2.0 error codes but with specific scenarios:

Error Code	Oten Scenario	When It Occurs	HTTP Status	Retryable
invalid_request	Missing request parameter	• Missing request parameter when request_uri not provided • Neither request nor request_uri provided • Both request and request_uri provided	400	No
invalid_request	JAR expired	• JWT exp claim exceeded • Token older than 5 minutes	400	Yes
invalid_request	Missing parameters	• Missing required OAuth parameters • Missing code_verifier for PKCE • Missing client_secret for confidential clients	400	No
invalid_client	IP not whitelisted	• Client IP not in configured whitelist • Client credentials grant from unauthorized IP • Missing IP address in client credentials requests	401	No
invalid_client	Client not confidential	• Client is not confidential (client_credentials) • Public client attempting client credentials grant	401	No
unauthorized_client	Public client restriction	• Public clients attempting client_credentials grant • Client not authorized for specific grant type	403	No

🔑 Token Endpoint Errors (/v1/oauth/token)

Token errors are returned as JSON in the response body:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": "invalid_grant",
  "error_description": "The provided authorization grant is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client"
}

Standard OAuth 2.0 Errors (RFC 6749)

Error Code	Description	When It Occurs	HTTP Status	Grant Types	Retryable
invalid_request	Missing required parameter or malformed request	• Missing client_id • Missing code (authorization_code) • Missing redirect_uri (authorization_code) • Missing refresh_token (refresh_token) • Missing client_secret (confidential clients)	400	All	No
invalid_client	Client authentication failed	• Invalid client credentials • Client not found • Wrong client_id • Client secret verification failed • IP address not in whitelist (client_credentials) • Client not confidential (client_credentials)	401	All	No
invalid_grant	Authorization grant invalid	• Invalid authorization code • Code already used • Code expired • Redirect URI mismatch • Invalid refresh token • Refresh token expired/revoked • PKCE verification failed	400	authorization_code, refresh_token	No
unauthorized_client	Client not authorized for grant type	• Client not authorized for grant type • Public client without PKCE	403	All	No
unsupported_grant_type	Grant type not supported	• Unsupported grant_type value • Grant type not implemented	400	All	No
invalid_scope	Requested scope invalid	• Invalid scope in refresh token request • Scope exceeds original grant	400	refresh_token	No
server_error	Internal server error	• Token generation failures • Database errors • Internal server errors	500	All	Yes

Grant Type Specific Error Scenarios

Authorization Code Grant (authorization_code)

Scenario	Error Code	Error Description	Retryable
Missing authorization code	invalid_request	"Authorization code is required"	No
Missing redirect URI	invalid_request	"Redirect URI is required"	No
Invalid authorization code	invalid_grant	"Invalid authorization code: code not found"	No
Code already used	invalid_grant	"Invalid authorization code: code already used"	No
Code expired	invalid_grant	"Invalid authorization code: code expired"	No
Redirect URI mismatch	invalid_grant	"Invalid authorization code: redirect URI mismatch"	No

Authorization Code Grant with PKCE

Scenario	Error Code	Error Description	Retryable
Code not issued with PKCE	invalid_grant	"Authorization code was not issued with PKCE"	No
Invalid code verifier	invalid_grant	"Invalid code verifier"	No
Missing code verifier	invalid_request	"Code verifier is required for PKCE"	No

Refresh Token Grant (refresh_token)

Scenario	Error Code	Error Description	Retryable
Missing refresh token	invalid_request	"Refresh token is required"	No
Invalid refresh token	invalid_grant	"Invalid refresh token"	No
Refresh token expired	invalid_grant	"Refresh token has expired"	No
Refresh token revoked	invalid_grant	"Refresh token has been revoked"	No
Token issued to different client	invalid_grant	"Refresh token was not issued for this client"	No

Client Credentials Grant (client_credentials)

Scenario	Error Code	Error Description	Retryable
Missing client secret	invalid_request	"Client secret is required"	No
Invalid client credentials	invalid_client	"Invalid client credentials: client not found"	No
Wrong client ID	invalid_client	"Invalid client id: wrong query"	No
IP address not in whitelist	invalid_client	"Invalid client IP: 192.168.1.100 is not in whitelist"	No
Missing IP address	invalid_client	"Missing IP address in client credentials request"	No
Client not confidential	invalid_client	"Client is not confidential"	No
Invalid client secret	invalid_client	"Invalid client credentials: invalid client secret"	No
Public client attempting grant	unauthorized_client	"Public clients are not authorized for client credentials grant"	No

Security-Enhanced Validation for Client Credentials Grant

IP Address Validation:

• When a client has configured IP whitelist, requests from non-whitelisted IPs are rejected

• IP validation is performed before credential verification for optimal security

• Missing IP address in requests triggers security warnings

• All IP validation failures are logged for security monitoring

Client Type Enforcement:

• Client credentials grant is restricted to confidential clients only

• Public clients attempting this grant receive unauthorized_client error

• Client type validation occurs before credential verification

🛡️ Error Response Parameters

Authorization Endpoint Error Parameters

Parameter	Required	Description
error	Yes	A single ASCII error code from the defined list
error_description	No	Human-readable ASCII text providing additional information
error_uri	No	A URI identifying a human-readable web page with information about the error
state	Conditional	Required if the "state" parameter was present in the client authorization request

Token Endpoint Error Parameters

Parameter	Required	Description
error	Yes	A single ASCII error code from the defined list
error_description	No	Human-readable ASCII text providing additional information
error_uri	No	A URI identifying a human-readable web page with information about the error

🎯 Error Handling Guidelines

Retryable vs Non-Retryable Errors

Retryable Errors (implement exponential backoff):

• server_error - Internal server issues

• temporarily_unavailable - Service overload

• access_denied - User can try again

• invalid_request (JAR expired) - Generate new JAR

• invalid_request (workspace required) - User can select workspace

• invalid_request (MFA required) - User can complete MFA

Non-Retryable Errors (require user/developer action):

• invalid_request (missing request parameter) - Implement JAR with request parameter

• invalid_request (missing parameters) - Fix request parameters

• invalid_client - Fix client configuration

• invalid_grant - Restart authorization flow

• unauthorized_client - Fix client permissions

• unsupported_grant_type - Use supported grant type

• invalid_scope - Request valid scopes

• invalid_request_object - Fix JAR implementation

Security Considerations

1. Don't expose sensitive information in error messages to end users

2. Always validate state parameter in authorization callbacks

3. Log detailed errors server-side for debugging

4. Use generic error messages for security-related errors

5. Implement rate limiting for error responses

Enhanced Security for Client Credentials Grant

IP Address Validation:

• Client credentials grant includes IP address checking for enhanced security

• When a client has configured IP whitelist, requests from non-whitelisted IPs are rejected

• IP validation failures are logged for security monitoring

• Missing IP address in client credentials requests triggers security warnings

Client Type Enforcement:

• Client credentials grant is restricted to confidential clients only

• Public clients attempting client credentials grant receive unauthorized_client error

• Client type validation occurs before credential verification

JAR (JWT-Secured Authorization Request) Requirements:

• Either request OR request_uri parameter is REQUIRED (RFC 9101)

• Cannot provide both request and request_uri parameters simultaneously

• Missing request parameter when request_uri is not provided results in invalid_request with message "Request parameter is required"

• JAR requests must be properly signed JWT tokens

User Experience Guidelines

1. Provide clear, actionable error messages to users

2. Offer retry options for retryable errors

3. Guide users to next steps (contact support, try again, etc.)

4. Avoid technical jargon in user-facing messages

5. Implement graceful fallbacks where possible

Related Documentation

• Common Errors: Step-by-step troubleshooting guide

• OAuth Error Handling: Implementation examples

• API Reference: Complete API documentation

• Security Best Practices: Security guidelines

---

References:

• RFC 6749 - OAuth 2.0 Authorization Framework

• RFC 9101 - JWT-Secured Authorization Request (JAR)