---
title: "Fail Token Request"
method: POST
path: "/api/{serviceId}/auth/token/fail"
tags: ["Token Endpoint"]
---

# Fail Token Request

`POST /api/{serviceId}/auth/token/fail`

This API generates a content of an error token response that the authorization server implementation
returns to the client application.
### Description
This API is supposed to be called from within the implementation of the token endpoint of the service
in order to generate an error response to the client application.
The description of the `/auth/token` API describes the timing when this API should be called. See
the description for the case of `action=PASSWORD`.
The response from `/auth/token/fail` API has some parameters. Among them, it is `action` parameter
that the authorization server implementation should check first because it denotes the next action
that the authorization server implementation should take. According to the value of `action`, the
authorization server implementation must take the steps described below.
**INTERNAL\_SERVER\_ERROR**
When the value of `action` is `INTERNAL\_SERVER\_ERROR`, it means that the request from the authorization
server implementation was wrong or that an error occurred in Authlete.
In either case, from the viewpoint of the client application, it is an error on the server side.
Therefore, the service implementation should generate a response to the client application with
HTTP status of "500 Internal Server Error".
The value of `responseContent` is a JSON string which describes the error, so it can be used
as the entity body of the response.
The following illustrates the response which the service implementation should generate and return
to the client application.
```
HTTP/1.1 500 Internal Server Error
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{responseContent}
```
The endpoint implementation may return another different response to the client application
since "500 Internal Server Error" is not required by OAuth 2.0.
**BAD\_REQUEST**
When the value of `action` is `BAD\_REQUEST`, it means that Authlete's `/auth/token/fail` API successfully
generated an error response for the client application.
The HTTP status of the response returned to the client application must be "400 Bad Request" and
the content type must be `application/json`.
The value of `responseContent` is a JSON string which describes the error, so it can be used
as the entity body of the response.
The following illustrates the response which the service implementation should generate and return
to the client application.
```
HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{responseContent}
```

## Path parameters

- `serviceId` string, required

## Request body

- TokenFailRequest
  - `ticket` string, required — The ticket issued from Authlete `/auth/token` API.
  - `reason` 'UNKNOWN' | 'INVALID_RESOURCE_OWNER_CREDENTIALS' | 'INVALID_TARGET', required — The reason of the failure of the token request.

## Response `200`

- TokenFailResponse
  - `resultCode` string — The code which represents the result of the API call.
  - `resultMessage` string — A short message which explains the result of the API call.
  - `action` 'INTERNAL_SERVER_ERROR' | 'BAD_REQUEST' — The next action that the authorization server implementation should take.
  - `responseContent` string — The content that the authorization server implementation is to return to the client application. Its format varies depending on the value of `action` parameter. See description for details.

## Other responses

- `400`
- `401`
- `403`
- `500`

---

[API](https://skmtc.dev/authlete/apis/authlete-api.md) · [All operations](https://skmtc.dev/authlete/apis/authlete-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/authlete/authlete-api/revisions/8a534bc68775/schema)