> For the complete documentation index, see [llms.txt](https://oten.gitbook.io/identity-support/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://oten.gitbook.io/identity-support/integration/prerequisites/appendix/error-codes-reference.md).

# 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](broken://pages/ChQqcK8cqX9LLgyQtBJT) for step-by-step solutions. 📖 **For Implementation**: See [Step 4: Handle Callback](broken://pages/QgyIUnxdUfokBnTwxCzw) 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 | <p>• Missing <code>response\_type</code><br>• Missing <code>client\_id</code><br>• Missing <code>redirect\_uri</code><br>• Invalid parameter values</p> | 400         | No        |
| `invalid_client`            | Client authentication failed                    | <p>• Client credentials not found<br>• Invalid client credentials during JAR verification</p>                                                           | 401         | No        |
| `unauthorized_client`       | Client not authorized for this method           | <p>• Client not authorized for authorization code flow<br>• Public client without PKCE</p>                                                              | 403         | No        |
| `unsupported_response_type` | Response type not supported                     | <p>• Unsupported <code>response\_type</code> value<br>• Only <code>code</code> is supported</p>                                                         | 400         | No        |
| `invalid_scope`             | Requested scope invalid                         | <p>• Invalid scope values<br>• Scope not supported by client</p>                                                                                        | 400         | No        |
| `access_denied`             | User denied authorization                       | <p>• User clicked "Deny" on consent screen<br>• User cancelled authentication</p>                                                                       | 400         | Yes       |
| `server_error`              | Internal server error                           | <p>• Database connection failures<br>• Token generation failures</p>                                                                                    | 500         | Yes       |
| `temporarily_unavailable`   | Service temporarily unavailable                 | <p>• Server maintenance<br>• High load conditions</p>                                                                                                   | 503         | Yes       |

### JAR-Specific Errors (RFC 9101)

| Error Code               | Description       | When It Occurs                                                                                                      | HTTP Status | Retryable |
| ------------------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------- | ----------- | --------- |
| `invalid_request_object` | Invalid JAR token | <p>• JWT parsing failed<br>• Invalid JWT signature<br>• Unsupported signing method<br>• Malformed JWT structure</p> | 400         | No        |
| `request_not_supported`  | JAR not supported | <p>• Server doesn't support JAR<br>• JAR disabled in configuration</p>                                              | 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** | <p>• <strong>Missing <code>request</code> parameter when <code>request\_uri</code> not provided</strong><br>• Neither <code>request</code> nor <code>request\_uri</code> provided<br>• Both <code>request</code> and <code>request\_uri</code> provided</p> | 400         | No        |
| `invalid_request`     | JAR expired                   | <p>• JWT <code>exp</code> claim exceeded<br>• Token older than 5 minutes</p>                                                                                                                                                                                | 400         | Yes       |
| `invalid_request`     | Missing parameters            | <p>• Missing required OAuth parameters<br>• Missing <code>code\_verifier</code> for PKCE<br>• Missing <code>client\_secret</code> for confidential clients</p>                                                                                              | 400         | No        |
| `invalid_client`      | **IP not whitelisted**        | <p>• <strong>Client IP not in configured whitelist</strong><br>• <strong>Client credentials grant from unauthorized IP</strong><br>• Missing IP address in client credentials requests</p>                                                                  | 401         | No        |
| `invalid_client`      | **Client not confidential**   | <p>• <strong>Client is not confidential</strong> (client\_credentials)<br>• Public client attempting client credentials grant</p>                                                                                                                           | 401         | No        |
| `unauthorized_client` | **Public client restriction** | <p>• <strong>Public clients attempting client\_credentials grant</strong><br>• Client not authorized for specific grant type</p>                                                                                                                            | 403         | No        |

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

Token errors are returned as JSON in the response body:

```json
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 | <p>• Missing <code>client\_id</code><br>• Missing <code>code</code> (authorization\_code)<br>• Missing <code>redirect\_uri</code> (authorization\_code)<br>• Missing <code>refresh\_token</code> (refresh\_token)<br>• Missing <code>client\_secret</code> (confidential clients)</p> | 400         | All                                 | No        |
| `invalid_client`         | Client authentication failed                    | <p>• Invalid client credentials<br>• Client not found<br>• Wrong client\_id<br>• Client secret verification failed<br>• <strong>IP address not in whitelist</strong> (client\_credentials)<br>• <strong>Client not confidential</strong> (client\_credentials)</p>                    | 401         | All                                 | No        |
| `invalid_grant`          | Authorization grant invalid                     | <p>• Invalid authorization code<br>• Code already used<br>• Code expired<br>• Redirect URI mismatch<br>• Invalid refresh token<br>• Refresh token expired/revoked<br>• PKCE verification failed</p>                                                                                   | 400         | authorization\_code, refresh\_token | No        |
| `unauthorized_client`    | Client not authorized for grant type            | <p>• Client not authorized for grant type<br>• Public client without PKCE</p>                                                                                                                                                                                                         | 403         | All                                 | No        |
| `unsupported_grant_type` | Grant type not supported                        | <p>• Unsupported <code>grant\_type</code> value<br>• Grant type not implemented</p>                                                                                                                                                                                                   | 400         | All                                 | No        |
| `invalid_scope`          | Requested scope invalid                         | <p>• Invalid scope in refresh token request<br>• Scope exceeds original grant</p>                                                                                                                                                                                                     | 400         | refresh\_token                      | No        |
| `server_error`           | Internal server error                           | <p>• Token generation failures<br>• Database errors<br>• Internal server errors</p>                                                                                                                                                                                                   | 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**](broken://pages/ChQqcK8cqX9LLgyQtBJT): Step-by-step troubleshooting guide
* [**OAuth Error Handling**](https://gitlab.silvertiger.tech/documents/idp/-/blob/main/best-practices/oauth-error-handling.md): Implementation examples
* [**API Reference**](broken://pages/rBfeuN3JiwHAXoU2ybbc): Complete API documentation
* [**Security Best Practices**](broken://pages/9YmJ1SYdIDChDe4DceZt): Security guidelines

***

**References:**

* [RFC 6749 - OAuth 2.0 Authorization Framework](https://tools.ietf.org/html/rfc6749)
* [RFC 9101 - JWT-Secured Authorization Request (JAR)](https://tools.ietf.org/html/rfc9101)