Token Issuance Endpoint Errors

 

The Azure AD token issuance endpoint uses HTTP error codes because the client calls this endpoint directly. This differs from the authorization endpoint that is loaded in a browser. The Azure AD token issuance endpoint uses the following error codes. In addition to the HTTP status code, the Azure AD token issuance endpoint returns a JSON document with objects that describe the error.

For example, the Azure AD token issuance endpoint returns an error like the following one when the value of the client_id parameter in the request is invalid.

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{"error":"invalid_request","error_description":"AADSTS90011: Request is ambiguous, multiple application identifiers found. Application identifiers: '197451ec-ade4-40e4-b403-02105abd9049, 597451ec-ade4-40e4-b403-02105abd9049'.\r\nTrace ID: 4457d068-2a03-42b2-97f2-d55325289d86\r\nCorrelation ID: 6b3474d8-233e-463f-b0a3-86433d8ba889\r\nTimestamp: 2013-12-31 06:31:41Z","error_codes":[90011],"timestamp":"2013-12-31 06:31:41Z","trace_id":"4457d068-2a03-42b2-97f2-d55325289d86","correlation_id":"6b3474d8-233e-463f-b0a3-86433d8ba889"}

HTTP Status Codes

The following table lists the HTTP status codes that the token issuance endpoint returns. In some cases, the error code is sufficient to describe the response, but in case of errors, you will need to parse the accompanying JSON document and examine its error code.

HTTP Code

Description

400

Default HTTP code. Used in most cases.

401

Authentication failed. For example, the request is missing the client_secret parameter.

403

Authorization failed. For example, the user does not have permission to access the resource.

500

An internal error has occurred at the service. Retry the request.

JSON Document Objects in the Error Response

When an error occurs, in addition to the HTTP Code, the Azure AD token issuance endpoint returns a JSON document. The following table lists the object in the document.

JSON Object

Description

error

An error code value defined in Section 5.2 of the OAuth 2.0 Authorization Framework. The next table describes the error codes that Azure AD returns.

error_description

A more detailed description of the error. This message is not intended to be end-user friendly.

timestamp

The date and time that the error occurred in Universal Coordinated Time (UTC).

trace_id

An ID that identifies the error trace.

correlation_id

A value generated by the client. This ID is included in the JSON error document when the request to the token issuance enpoint includes this value in the client-request-id header. This ID may be used by other calls in the same session.

error_codes

Contains a list of error codes that map to different conditions of the service. Do not use these codes in your application logic. However, you can use them to diagnose an issue and search for information online by error code.

JSON Document Error Code Values

The following table describes the error codes (error parameter values) that the Azure AD token issuance endpoint returns.

Error Code

Description

Client Action

invalid_request

Protocol error, such as a missing required parameter.

Fix and resubmit the request. For reference, use the protocol documentation and Authorization Code Grant Flow. This is a development error is typically caught during initial testing.

invalid_grant

The authorization grant (or its parameters) or refresh token is invalid, expired, or revoked.

Fix and resubmit the request. For reference, use the protocol documentation and Authorization Code Grant Flow. This is a development error is typically caught during initial testing.

unauthorized_client

The authenticated client is not authorized to use this authorization grant type.

This usually occurs when the client application is not registered in Azure AD or is not added to the user's Azure AD tenant. The application can prompt the user with instruction for installing the application and adding it to Azure AD. For more information, see Application Access.

invalid_client

Client authentication failed.

The client credentials are not valid. To fix, the application administrator updates the credentials. 

unsupported_grant_type

The authorization server does not support the authorization grant type.

Change the grant type in the request. This type of error should occur only during development and be detected during initial testing. For information, see Authorization Code Grant Flow and Service to Service Calls Using Client Credentials.

invalid_resource

The target resource is invalid because it does not exist, Azure AD cannot find it, or it is not correctly configured.

This indicates the resource has not been configured in the tenant. The application can prompt the user with instruction for installing the application and adding it to Azure AD. For more information, see Application Access.

interaction_required 

The request requires user interaction. For example, an additional authentication step is required.

Retry the request with the same resource.

temporarily_unavailable

The server is temporarily too busy to handle the request.

Retry the request. The client application might explain to the user that its response is delayed due a temporary condition.

See Also

Error Handling in OAuth 2.0
Authorization Endpoint Errors
Errors from Secured Resources
OAuth 2.0 in Azure AD
Best Practices for OAuth 2.0 in Azure AD