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

For successful requests, PayPal returns HTTP 2XX status codes.

For failed requests, PayPal returns HTTP 4XX or 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

PayPal returns these HTTP 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.
400 Bad Request INVALID_REQUEST. Request is not well-formed, syntactically incorrect, or violates schema.
401 Unauthorized AUTHENTICATION_FAILURE. Authentication failed due to invalid authentication credentials.
403 Forbidden NOT_AUTHORIZED. Authorization failed due to insufficient permissions.
404 Not Found RESOURCE_NOT_FOUND. The specified resource does not exist.
405 Method Not Allowed METHOD_NOT_SUPPORTED. The server does not implement the requested HTTP method.
406 Not Acceptable MEDIA_TYPE_NOT_ACCEPTABLE. The server does not implement the media type that would be acceptable to the client.
415 Unsupported Media Type UNSUPPORTED_MEDIA_TYPE. The server does not support the request payload’s media type.
422 Unprocessable Entity UNPROCESSABLE_ENTITY. The API cannot complete the requested action, or the request action is semantically incorrect or fails business validation.
429 Unprocessable Entity RATE_LIMIT_REACHED. Too many requests. Blocked due to rate limiting.
500 Internal Server Error INTERNAL_SERVER_ERROR. An internal server error has occurred.
503 Service Unavailable SERVICE_UNAVAILABLE. Service Unavailable.

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

For authorization errors, PayPal returns the HTTP 401 Unauthorized status code. See OAuth 2.0 authorization protocol.

Access token-related issues often cause authorization errors.

Ensure that the access token is valid and present and not expired.

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.