Error Codes Reference
Last updated
Last updated
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.
/v1/oauth/authorize)Authorization errors are returned as URL parameters in the redirect URI:
invalid_request
Missing required parameter or malformed request
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
Oten IDP uses standard OAuth 2.0 error codes but with specific scenarios:
Token errors are returned as JSON in the response body:
IP Address Validation:
Client Type Enforcement:
Retryable Errors (implement exponential backoff):
Non-Retryable Errors (require user/developer action):
IP Address Validation:
Client Type Enforcement:
JAR (JWT-Secured Authorization Request) Requirements:
References:
• Missing response_type
• Missing client_id
• Missing redirect_uri
• Invalid parameter values
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
invalid_request
Missing request parameter
400
No
invalid_request
JAR expired
• JWT exp claim exceeded
• Token older than 5 minutes
400
Yes
invalid_request
Missing parameters
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
invalid_request
Missing required parameter or malformed request
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
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
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
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
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
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 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
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
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
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
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
Don't expose sensitive information in error messages to end users
Always validate state parameter in authorization callbacks
Log detailed errors server-side for debugging
Use generic error messages for security-related errors
Implement rate limiting for error responses
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 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
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
Provide clear, actionable error messages to users
Offer retry options for retryable errors
Guide users to next steps (contact support, try again, etc.)
Avoid technical jargon in user-facing messages
Implement graceful fallbacks where possible
Common Errors: Step-by-step troubleshooting guide
OAuth Error Handling: Implementation examples
API Reference: Complete API documentation
Security Best Practices: Security guidelines
• Missing request parameter when request_uri not provided
• Neither request nor request_uri provided
• Both request and request_uri provided
• Missing required OAuth parameters
• Missing code_verifier for PKCE
• Missing client_secret for confidential clients
• Missing client_id
• Missing code (authorization_code)
• Missing redirect_uri (authorization_code)
• Missing refresh_token (refresh_token)
• Missing client_secret (confidential clients)