API responses

DocsCurrentLast updated: September 6th 2022, @ 4:55:20 pm


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 codeDescription
200 OKThe request succeeded.
201 CreatedA 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 AcceptedThe server accepted the request and will execute it later.
204 No ContentThe 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 codeDescriptionPossible causes and solutions
400 Bad RequestINVALID_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 FoundRESOURCE_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 AllowedMETHOD_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 AcceptableMEDIA_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 TypeUNSUPPORTED_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 EntityUNPROCESSABLE_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 RequestsRATE_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 codeDescriptionPossible causes and solutions
500 Internal Server ErrorINTERNAL_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 UnavailableSERVICE_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 typeDescription
CharacterNames, addresses, and phone numbers have maximum character limits.
NumericCredit 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.
MonetaryUse the right currency.
FormatProperly 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 codeDescriptionPossible causes and solutions
400 Bad RequestINVALID_REQUEST. Invalid scope requested.Resend with a valid scope.
400 Bad RequestINVALID_REQUEST. The refresh_token is a required parameter.Add the refresh_token parameter and value.
400 Bad RequestINVALID_REQUEST. Current version only supports token for response_type.Incorrect response type sent.
400 Bad RequestINVALID_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 RequestINVALID_REQUEST. The redirect_uri is a required parameter.Resend with this parameter and its value.
400 Bad RequestUNSUPPORTED_GRANT_TYPE. Unsupported grant_type.Specify a valid grant_type.
400 Bad RequestINVALID_RESPONSE_TYPE. Invalid response type for the request: [code].Use the grant_type=client_credentials with response_type=token.
401 Bad RequestINVALID_CLIENT. Client authentication failed.The Authorization header is not present.
401 Bad RequestINVALID_CLIENT. Client credentials are missing.Invalid basic authorization token.
401 Bad RequestINVALID_REQUEST. The refresh token is invalid.Resend with a valid refresh_token.
401 UnauthorizedINVALID_AUTHZ_CODE. The authorization code is invalid.Check your authorization_code and resend.
401 UnauthorizedINVALID_CLIENT. Client authentication failed.The Base64-encoded client credentials in the Authorization header are invalid.
401 UnauthorizedINVALID_REDIRECT_URI. The redirect URI does not match.The redirect_uri should match the one configured during the application registration.
401 UnauthorizedRISK_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 UnauthorizedINVALID_USER. Device authentication failed.Incorrect device information.
401 UnauthorizedINVALID_REQUEST. Cannot decrypt refresh token: Base64 Decode Failed.Invalid refresh token passed when trying to get an AT from RT.
401 UnauthorizedINVALID_REQUEST. Cannot decrypt refresh token: Input length of 0 received; expected at least 36.Incorrect refresh token.
401 UnauthorizedINVALID_AUTHZ_CODE. Authorization code is invalid.Authorization code not passed or invalid.
401 UnauthorizedINVALID_AUTHZ_CODE. Authorization code not found in cache.Use a new authorization code.
401 UnauthorizedINVALID_TOKEN. Token signature verification failed.
401 UnauthorizedUNAUTHORIZED_CLIENT. Client not authorized.Check your permissions and try again.
401 UnauthorizedREMEMBER_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 ForbiddenNOT_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:

ElementRequiredDescription
hrefRequiredThe 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.
relRequiredThe 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.

methodOptionalThe HTTP method. If present, use this method to make a request to the target URL. If absent, the default method is GET.