Response format
The service response is a JSON document in UTF‑8, see The application/json Media Type for JavaScript Object Notation (JSON) and official JSON site. The contents depend on the request results.
Successful response example
HTTP/1.1 200 OK Content-Type: application/json Content-Length: 51 Expires: Thu, 01 Dec 2019 16:00:00 GMT Cache-Control: no-cache { "param1":"value1", "param2":"value2" }
The response has HTTP headers to forbid proxy servers and local browsers to cache the content.
The response may contain extra fields not described in this protocol. The application is to ignore them.
If authorization fails, the server responds with a 4xx HTTP code. Possible reasons for rejection:
- The request cannot be parsed;
- The request does not include the HTTP
Authorization
header; - The
Authorization
header specifies a nonexistent, invalid or expired token; - The token does not have permissions for the requested operation.
The response contains the
WWW-Authenticate
header (in accordance with The OAuth 2.0 Authorization Framework: Bearer Token Usage).When authorization of the request is denied, the following fields are present in the response:
Field | Description |
---|---|
error | Code of the reason for authorization refusal. |
error_description | Additional text description of the reason for refusal. |
Codes for reasons for authorization refusal:
HTTP response code | Value of the error field | Description |
---|---|---|
400 | invalid_request | HTTP request does not conform to protocol format. Unable to parse HTTP request, or the Authorization header is missing or has an invalid value. |
401 | invalid_token | Nonexistent, expired, or revoked token specified. |
403 | insufficient_scope | The token does not have permissions for the requested operation. |
Response example for missing header
HTTP/1.1 400 Bad Request WWW-Authenticate: Bearer error="invalid_request"
Response example for expired token
HTTP/1.1 401 Unauthorized WWW-Authenticate: Bearer error="invalid_token", error_description="The access token has expired"
Response example for token without required permissions
HTTP/1.1 403 Forbidden WWW-Authenticate: Bearer error="insufficient_scope", error_description="Payment forbidden by application authorization parameters"
If a technical error occurs, the server responds with the HTTP code 500 Internal Server Error. The application should repeat the request with the same parameters later.
See also