# 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)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://oten.gitbook.io/identity-support/integration/prerequisites/appendix/error-codes-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.