Almost all errors returned by our APIs includes an error code in the response body (error) and/or in the HTTP status code. These codes are used to identify the type of error that occurred and help you find the appropriate solution.

Below is a list of error codes you may encounter when using our APIs, along with their meanings and suggested actions.

invalid_request

HTTP Status Code : 400 Bad Request

The request is missing a required parameter, includes an unsupported parameter value, or is otherwise malformed. Check the request for missing or incorrect parameters.

invalid_client

HTTP Status Code : 401 Unauthorized

Client authentication failed. For RFC 8693 token exchange, use HTTP Basic authentication with the service’s registered confidential client ID and secret. Check that the client is active and belongs to the issuer whose token endpoint you called. Missing or invalid Basic credentials, public clients, and agent or CIMD identifiers are rejected with Client authentication failed and a WWW-Authenticate: Basic realm="AuthPI token endpoint" header. Sending credentials in the exchange request body instead is invalid_request.

invalid_grant

HTTP Status Code : 400 Bad Request

The authorization code, refresh token, or subject access token cannot be used for this request. Check its expiry and revocation state. Authorization codes and refresh tokens must also match their original client and flow.

For RFC 8693 token exchange, Token exchange rejected can mean that the subject token is invalid, expired, revoked, already delegated, or issued for a source resource outside the service’s exchange policy. It also covers an inactive user or an invalid selected organization membership. Obtain a fresh user access token from the same issuer, check its source audience and organization claims, and confirm that the user and selected membership are still active. The response intentionally does not identify which subject check failed.

invalid_scope

HTTP Status Code : 400 Bad Request for RFC 8693 token exchange; 422 Unprocessable Entity for refresh-token and client-credentials scope rejections

The requested scope is invalid or exceeds the grant. For token exchange, every requested scope must be a concrete authorization scope present in the subject token’s OAuth grant and in both source and target exchange policies, and permitted by the user’s current organization membership. Role labels and wildcard scopes cannot be requested. Request only scopes that satisfy all four checks; the exchange rejects the request instead of silently dropping disallowed scopes. See the Token Exchange reference.

invalid_target

HTTP Status Code : 400 Bad Request for token/direct errors; 302 Found for a trusted authorization redirect

In authorization-code and refresh-token flows, an OAuth resource selection is malformed, required but missing, unknown, disallowed by issuer or client policy, or incompatible with the requested scopes. RFC 8693 token exchange also uses this error when its target resource is missing, repeated, malformed, or absent from the service’s token_exchange.target_resources. Send exactly one permitted target resource. A subject token with an unapproved source audience instead returns invalid_grant. At /token, this is a JSON error response. At /authorize, AuthPI redirects the error only after validating that the redirect URI belongs to the client; otherwise it returns JSON directly. The unchanged client_credentials resource-audience path uses invalid_request for malformed input. See Resource Indicators and Token Exchange.

invalid_content_type

HTTP Status Code : 415 Unsupported Media Type

The request’s Content-Type header is not supported by the server. Ensure that the Content-Type header is set to a supported type, such as application/json.

access_denied | insufficient_scope

HTTP Status Code : 403 Forbidden

The request was valid, but the server is refusing to respond to it. This may be due to insufficient permissions or an invalid token. Check the permissions of the user or client making the request.

session_expired

HTTP Status Code : 401 Unauthorized

The request requires authentication, but the session has expired. The user must re-authenticate to obtain a new session token. Check the session expiration settings and ensure the user is logged in.

unauthorized_client

HTTP Status Code : 400 Bad Request for RFC 8693 token exchange; 403 Forbidden for direct authorization-code, refresh-token, and client-credentials rejections

The client is not authorized to use the requested grant or issuer. For token exchange, authentication succeeded but the service lacks a valid exchange capability. Check its settings.openid.token_exchange policy and exchange-only M2M configuration. Setting the client’s classification to internal or listing a resource in allowed_resources does not grant exchange authority. See the Token Exchange reference.

not_found

HTTP Status Code : 404 Not Found

The requested resource or page could not be found. Check the path or the resource ID and ensure it exists.

conflict

HTTP Status Code : 409 Conflict

The request could not be completed due to a conflict with the current state of the resource. This may occur when trying to create a resource that already exists or when trying to update a resource that has been modified since it was last retrieved. Check the resource’s state and try again.

precondition_failed

HTTP Status Code : 412 Precondition Failed

The request included an If-Match header whose value does not match the resource’s current ETag. The resource has been modified by another client since you last retrieved it. Fetch the latest version and retry your update. See the Conditional Requests guide for details.

usage_limit_exceeded

HTTP Status Code : 429 Too Many Requests

The request was rejected because the user has exceeded their usage limits. This may occur if the user has made too many requests in a short period of time. Check the usage limits and try again later.

server_error

HTTP Status Code : 500 Internal Server Error

An unexpected error occurred on the server. This is a generic error message and may not provide specific details about the issue. If this error persists, please contact support.