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

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

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"
}

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:

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

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

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

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"
}

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:

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

Responses

Learn more about PayPal API HTTP status codes, JSON response bodies, API flows and contextual HATEOAS links.

HTTP status codes

Successful requests

Failed requests

HTTP `4XX` status codes

HTTP `5XX` status codes

Examples

Validation errors

Authorization errors

Example

Request

Response

HATEOAS links

On this page

On this page

On this page

Responses

Learn more about PayPal API HTTP status codes, JSON response bodies, API flows and contextual HATEOAS links.

HTTP status codes

Successful requests

Failed requests

HTTP `4XX` status codes

HTTP `5XX` status codes

Examples

Validation errors

Authorization errors

Example

Request

Response

HATEOAS links

On this page

On this page

Responses

Learn more about PayPal API HTTP status codes, JSON response bodies, API flows and contextual HATEOAS links.

HTTP 4XX status codes

HTTP 5XX status codes

On this page

On this page

On this page

If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more

Responses

Learn more about PayPal API HTTP status codes, JSON response bodies, API flows and contextual HATEOAS links.

HTTP 4XX status codes

HTTP 5XX status codes

On this page

On this page

HTTP `4XX` status codes

HTTP `5XX` status codes

HTTP `4XX` status codes

HTTP `5XX` status codes