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 1994 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.

Tip. 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 ForbiddenWWW-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.