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