# Responses (/api/rest/responses)
Learn more about PayPal API HTTP status codes, JSON response bodies, API flows and contextual HATEOAS links.
PayPal API calls return HTTP status codes. Some API calls also return JSON response bodies that include information about the resource including one or more contextual HATEOAS links. Use these links to request more information about and construct an API flow that is relative to a specific request. Each REST API request returns an HTTP status code.
## HTTP status codes [#http-status-codes]
### Successful requests [#successful-requests]
For successful requests, PayPal returns HTTP 2XX status codes.
Status code
Description
200 OK
The request succeeded.
201 Created
A POST method successfully created a resource. If the
resource was already created by a previous execution of the same method,
for example, the server returns the HTTP 200 OK status code.
202 Accepted
The server accepted the request and will execute it later.
204 No Content
The server successfully executed the method but returns no response body.
## Failed requests [#failed-requests]
For failed requests, PayPal returns HTTP 4XX status codes if something passed in the request has an error or 5XX status codes when something is wrong on our end with a server or service.
For authentication specific HTTP 4XX status codes, see Authorization errors.
HTTP 4XX status codes
Status code
Description
Possible causes and solutions
400 Bad Request
INVALID\_REQUEST. Request is not well-formed, syntactically
incorrect, or violates schema.
See Validation errors. The server could
not understand the request. Indicates one of these conditions:
The API cannot convert the payload data to the underlying data type.
The data is not in the expected data format.
A required field is not available.
A simple data validation error occurred.
404 Not Found
RESOURCE\_NOT\_FOUND. The specified resource does not exist.
The server did not find anything that matches the request URI. Either the
URI is incorrect or the resource is not available. For example, no data
exists in the database at that key.
405 Method Not Allowed
METHOD\_NOT\_SUPPORTED. The server does not implement the
requested HTTP method.
The service does not support the requested HTTP method. For example,{" "}
PATCH.
406 Not Acceptable
MEDIA\_TYPE\_NOT\_ACCEPTABLE. The server does not implement the
media type that would be acceptable to the client.
The server cannot use the client-request media type to return the response
payload. For example, this error occurs if the client sends an{" "}
Accept: application/xml request header but the API can
generate only an application/json response.
409 Conflict
RESOURCE\_CONFLICT. Request cannot be processed as it
conflicts with another request.
The API cannot complete the requested action as it conflicts with another
request that is currently being processed. Retry the request later.
415 Unsupported Media Type
UNSUPPORTED\_MEDIA\_TYPE. The server does not support the
request payload's media type.
The API cannot process the media type of the request payload. For example,
this error occurs if the client sends a{" "}
Content-Type: application/xml request header but the API can
only accept application/json request payloads.
422 Unprocessable Entity
UNPROCESSABLE\_ENTITY. The API cannot complete the requested
action, or the request action is semantically incorrect or fails business
validation.
The API cannot complete the requested action and might require interaction
with APIs or processes outside of the current request. No systemic
problems limit the API from completing the request. For example, this
error occurs for any business validation errors, including errors that are
not usually of the 400 type.
429 Too Many Requests
RATE\_LIMIT\_REACHED. Too many requests. Blocked due to rate
limiting.
The rate limit for the user, application, or token exceeds a predefined
value. See{" "}
{" "}
RFC 6585
.
HTTP 5XX status codes
> **Info:** Note: An HTTP 5xx or network timeout from an{" "}
> /execute or /capture endpoint could have resulted
> in the creation of a PayPal transaction. To be informed of the transaction,
> it is recommended that you repeat the same /execute or{" "}
> /capture call at least once, with the same{" "}
> PayPal-Request-Id HTTP header as before. See:{" "}
> API idempotency
Status code
Description
Possible causes and solutions
|
|
500 Internal Server Error
INTERNAL\_SERVER\_ERROR. An internal server error has occurred.
A system or application error occurred. Although the client appears to
provide a correct request, something unexpected occurred on the server.
503 Service Unavailable
SERVICE\_UNAVAILABLE. Service Unavailable.
The server cannot handle the request for a service due to temporary
maintenance.
### Examples [#examples]
For all errors except Identity errors, PayPal returns an error response body that includes additional error details in this format.
> **Info:** Note: The fields returned in the details array
> vary by error.
```json
{
"name": "ERROR_NAME",
"message": "Error message.",
"debug_id": "debug_ID",
"details": [
{
"field": "field_name",
"value": "value_passed",
"location": "field_location",
"issue": "problem_with_field",
"description": "Error description."
}
],
"links": [
{
"https://error_documentation_link",
"rel": "information_link",
"encType": "application/json"
}
]
}
```
The response body for Identity errors includes additional error details in this format:
```json
{
"error": "ERROR_NAME",
"error_description": "ERROR_DESCRIPTION"
}
```
## Validation errors [#validation-errors]
For validation errors, PayPal returns the HTTP 400 Bad Request status code.
To prevent validation errors, ensure that parameters are the right type and conform to constraints:
Parameter type
Description
Character
Names, addresses, and phone numbers have maximum character limits.
Numeric
Credit cards, amounts, and card verification value (CVV) must use
non-negative numeric values and have required formats. For example, a CVV
must be three or four numbers.
Monetary
Use the right currency.
Format
Properly format the JSON sent in the body of your request. For example, no
trailing commas.
## Authorization errors [#authorization-errors]
Paypal follows industry standard OAuth 2.0 authorization protocol and returns the HTTP 400, 401, and 403 status code for authorization errors.
> **Tip:** **Tip:** These are usually access token-related issues and can be cleared by making
> sure that the token is present and hasn't expired.
Status code
Description
Possible causes and solutions
400 Bad Request
INVALID\_REQUEST. Invalid scope requested.
Resend with a valid scope.
400 Bad Request
INVALID\_REQUEST. The refresh\_token is a required
parameter.
Add the refresh\_token parameter and value.
400 Bad Request
INVALID\_REQUEST. Current version only supports{" "}
token for response\_type.
Incorrect response type sent.
400 Bad Request
INVALID\_REQUEST. No permissions to set{" "}
target\_client\_id.
The client\_id should have the GRANT\_PROXY\_CLIENT{" "}
scope to use the target\_client\_id parameter.
400 Bad Request
INVALID\_REQUEST. The redirect\_uri is a required
parameter.
Resend with this parameter and its value.
400 Bad Request
UNSUPPORTED\_GRANT\_TYPE. Unsupported grant\_type.
Specify a valid grant\_type.
400 Bad Request
INVALID\_RESPONSE\_TYPE. Invalid response type for the request:
\[code].
Use the grant\_type=client\_credentials with{" "}
response\_type=token.
401 Bad Request
INVALID\_CLIENT. Client authentication failed.
The Authorization header is not present.
401 Bad Request
INVALID\_CLIENT. Client credentials are missing.
Invalid basic authorization token.
401 Bad Request
INVALID\_REQUEST. The refresh token is invalid.
Resend with a valid refresh\_token.
401 Unauthorized
INVALID\_AUTHZ\_CODE. The authorization code is invalid.
Check your authorization\_code and resend.
401 Unauthorized
INVALID\_CLIENT. Client authentication failed.
The Base64-encoded client credentials in the Authorization{" "}
header are invalid.
401 Unauthorized
INVALID\_REDIRECT\_URI. The redirect URI does not match.
The redirect\_uri should match the one configured during the
application registration.
401 Unauthorized
RISK\_DECLINE. Request declined by risk.
This request was declined due to risk issues.
401 Unauthorized
INVALID\_USER. Device authentication failed.
Incorrect device information.
401 Unauthorized
INVALID\_REQUEST. Cannot decrypt refresh token: Base64 Decode
Failed.
Invalid refresh token passed when trying to get an AT from RT.
401 Unauthorized
INVALID\_REQUEST. Cannot decrypt refresh token: Input length
of 0 received; expected at least 36.
Incorrect refresh token.
401 Unauthorized
INVALID\_AUTHZ\_CODE. Authorization code is invalid.
Authorization code not passed or invalid.
401 Unauthorized
INVALID\_AUTHZ\_CODE. Authorization code not found in cache.
Use a new authorization code.
401 Unauthorized
INVALID\_TOKEN. Token signature verification failed.
|
401 Unauthorized
UNAUTHORIZED\_CLIENT. Client not authorized.
Check your permissions and try again.
401 Unauthorized
REMEMBER\_ME\_EXPIRED. Remember Me on the device has expired.
Legal mandate to clear off One Touch in a country-specific
pre-configuration period. Current expiry is set at six months.
403 Forbidden
NOT\_AUTHORIZED. Authorization failed due to insufficient
permissions.
The client is not authorized to access this resource although it might
have valid credentials. For example, the client does not have the correct
OAuth 2.0 scope. Additionally, a business-level authorization error might
have occurred. For example, the account holder does not have sufficient
funds.
### Example [#example]
In this example, an invalid client ID is passed in the request to get an access token.
#### Request [#request]
```bash
curl -v https://api-m.sandbox.paypal.com/v1/oauth2/token \\
-H "Accept: application/json" \\
-H "Accept-Language: en_US" \\
-u "bad_client_id:secret" \\
-d "grant_type=client_credentials"
```
#### Response [#response]
This unsuccessful request returns the HTTP 401 Unauthorized status code and a JSON response body that lists the error name and the error description.
```json
{
"error": "invalid_client",
"error_description": "Client Authentication failed"
}
```
## HATEOAS links [#hateoas-links]
Hypermedia as the Engine of Application State (HATEOAS) is a constraint of the REST application architecture that distinguishes it from other network application architectures.
This excerpt from a sample response shows an array of HATEOAS links:
```json
{
"links": [
{
"href": "https://api-m.paypal.com/v1/payments/sale/36C38912MN9658832",
"rel": "self",
"method": "GET"
},
{
"href": "https://api-m.paypal.com/v1/payments/sale/36C38912MN9658832/refund",
"rel": "refund",
"method": "POST"
},
{
"href": "https://api-m.paypal.com/v1/payments/payment/PAY-5YK922393D847794YKER7MUI",
"rel": "parent_payment",
"method": "GET"
}
]
}
```
Use the links in this example, as follows:
* To get more information about the request, combine the GET method and the target href of the self link.
* To request a refund, combine the POST method and the target href of the refund link.
* To get information about the parent payment, combine the GET method and the target href of the parent\_payment link.
The elements in each link object in the links array are:
Element
Required
Description
href
Required
The complete target URL, or link, to combine with the HTTP{" "}
method to make the related call. href is the key
HATEOAS component that links a completed call with a subsequent call.
rel
Required
The link relationship type, or how the href link relates to
the previous call. For a complete list of the link relationship types, see{" "}
{" "}
> Link Relationship Types
method
Optional
The HTTP method. If present, use this method to make a request to the
target URL. If absent, the default method is GET.