API responses


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

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

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.
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 Unprocessable Entity 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

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

For all errors except Identity errors, PayPal returns an error response body that includes additional error details in this format.

Note: The fields returned in the details array vary by error.

{
  "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:

{
  "error": "ERROR_NAME",
  "error_description": "ERROR_DESCRIPTION"
}

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 while a credit card number must contain only 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

Paypal follows industry standard OAuth 2.0 authorization protocol and returns the HTTP 400, 401, and 403 status code for authorization errors.

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. Risk can decline due to Bad IP, OFAC check, and suspicious fraudulent activity. Risk decline reasons are not transparent, so check with risk.
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

In this example, an invalid client ID is passed in the request to get an access token.

Request

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

This unsuccessful request returns the HTTP 401 Unauthorized status code and a JSON response body that lists the error name and the error description.

{
  "error":"invalid_client",
  "error_description":"Client Authentication failed"
}

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:

{  
  "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.