Common errors
The following table lists the most common errors returned by the Orders v2 API. To find more API-specific error details, see the Orders v2 API errors documentation.
HTTP status code | Error message | Error Code |
---|---|---|
400 Bad Request |
Request is not well-formed, syntactically incorrect, or violates schema. | INVALID_REQUEST |
401 Unauthorized |
Authentication failed due to missing Authorization header, or invalid authentication credentials. | AUTHENTICATION_FAILURE |
403 Forbidden |
Authorization failed due to insufficient permissions. | NOT_AUTHORIZED |
404 Not Found |
The specified resource does not exist. | RESOURCE_NOT_FOUND |
422 Unprocessable Entity |
The requested action could not be performed, semantically incorrect, or failed business validation. | UNPROCESSABLE_ENTITY |
500 Internal Server Error |
An internal server error has occurred. | INTERNAL_SERVER_ERROR |
503 Service Unavailable |
Service Unavailable. | SERVICE_UNAVAILABLE |
Error samples
This section shows 4 common error scenarios for the Orders v2 API.
Internal Server Error, status code 500
The Orders v2 API returns a 500
status code when a request fails due to an internal server error. For example, one of the servers may have some underlying issues, or some internal exception may not have been handled correctly.
The following sample request tries to create and capture an order, and the request fails with a 500
response.
Create order request
curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders/
-H 'Content-Type: application/json'
-H 'Authorization: Bearer ACCESS_TOKEN'
-d '{
"intent": "CAPTURE",
"purchase_units": [
{
"reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f7b",
"amount": {
"currency_code": "USD",
"value": "10.00"
}
}
],
"payment_source": {
"paypal": {
"address": {
"address_line_1": "2211 N First Street",
"address_line_2": "17.3.160",
"admin_area_1": "CA",
"admin_area_2": "San Jose",
"postal_code": "95131",
"country_code": "US"
},
"email_address":"johndoe@paypal.com",
"payment_method_preference": "IMMEDIATE_PAYMENT_REQUIRED",
"experience_context": {
"return_url": "https://example.com/returnUrl",
"cancel_url": "https://example.com/cancelUrl"
}
}
}
}'
Error response
{
"name": "INTERNAL_SERVER_ERROR",
"message": "An internal server error has occurred.",
"debug_id": "90957fca61718",
"links": [
{
"href": "https://developer.paypal.com/api/orders/v2/#error-INTERNAL_SERVER_ERROR",
"rel": "information_link",
"method": "GET"
}
]
}
Unprocessable Entity Error, status code 422
The API returns a 422
status code when an order is unsuccessful because of a failed business validation, such as when a buyer uses an expired card.
The following code sample attempts to create and authorize an order with an expired payment card, and the request fails with a 422
response.
Create order request
curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders/
-H 'Content-Type: application/json'
-H 'Authorization: Bearer ACCESS_TOKEN'
-d '{
"intent": "AUTHORIZE",
"purchase_units": [
{
"reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
"amount": {
"currency_code": "USD",
"value": "100.00"
}
}
],
"payment_source": {
"card": {
"number": "4111111111111111",
"expiry": "2010-02",
"name": "John Doe",
"billing_address": {
"address_line_1": "2211 N First Street",
"address_line_2": "17.3.160",
"admin_area_1": "CA",
"admin_area_2": "San Jose",
"postal_code": "95131",
"country_code": "US"
},
"stored_credential": {
"payment_initiator": "MERCHANT",
"payment_type": "ONE_TIME",
"usage": "SUBSEQUENT"
}
}
}
}'
Error response
{
"name": "UNPROCESSABLE_ENTITY",
"details": [
{
"field": "/payment_source/card/expiry",
"location": "body",
"issue": "CARD_EXPIRED",
"description": "The card is expired."
}
],
"message": "The requested action could not be performed, semantically incorrect, or failed business validation.",
"debug_id": "866780170332c",
"links": [
{
"href": "https://developer.paypal.com/docs/api/orders/v2/#error-CARD_EXPIRED",
"rel": "information_link",
"method": "GET"
}
]
}
Bad Request, status code 400
The following code sample attempts to create an order with an invalid usage_pattern
, and the request fails with a 400
response because the request includes an incorrect or unsupported value.
Create order request
curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders/
-H 'Content-Type: application/json'
-H 'Authorization: Bearer ACCESS_TOKEN'
-d '{
"intent": "CAPTURE",
"purchase_units": [
{
"reference_id": "PUHF",
"amount": {
"currency_code": "USD",
"value": "10.00"
}
}
],
"payment_source": {
"paypal": {
"attributes": {
"customer": {
"id": "jd120252fg4dm"
},
"vault": {
"confirm_payment_token": "ON_ORDER_COMPLETION",
"usage_type": "MERCHANT",
"usage_pattern": "IMM3DI4T3"
}
}
}
}
}'
Error response
{
"name": "INVALID_REQUEST",
"message": "Request is not well-formed, syntactically incorrect, or violates schema.",
"debug_id": "10398537340c8",
"details": [
{
"field": "/payment_source/paypal/attributes/vault/usage_pattern",
"value": "IMM3DI4T3",
"location": "body",
"issue": "INVALID_PARAMETER_VALUE",
"description": "A parameter value is not valid."
}
],
"links": [
{
"href": "https://developer.paypal.com/docs/api/orders/v2/#error-INVALID_PARAMETER_VALUE",
"rel": "information_link"
}
]
}
Forbidden, status code 403
The API returns a 403
status code when either the API caller or the payee doesn't have the appropriate permissions for the request.
The following code sample attempts to create and capture an order without the correct permissions to send items.category
as DONATION
. The request fails with a 400
response.
Create order request
curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders/
-H 'Content-Type: application/json'
-H 'Authorization: Bearer ACCESS_TOKEN'
-d '{
"intent": "CAPTURE",
"purchase_units": [
{
"amount": {
"currency_code": "USD",
"value": "5.00",
"breakdown": {
"item_total": {
"currency_code": "USD",
"value": "5.00"
}
}
},
"items": [
{
"name": "Donation to WWF",
"unit_amount": {
"currency_code": "USD",
"value": "5.00"
},
"quantity": "1",
"category": "DONATION"
}
]
}
]
}'
Error response
{
"name": "NOT_AUTHORIZED",
"details": [
{
"issue": "PERMISSION_DENIED_FOR_DONATION_ITEMS",
"description": "The API Caller or Payee have not been granted appropriate permissions to send 'items.category' as 'DONATION'. Please speak to your account manager if you want to process these type of items."
}
],
"message": "Authorization failed due to insufficient permissions.",
"debug_id": "90957fca61718",
"links": [
{
"href": "https://developer.paypal.com/api/orders/v2/#error-PERMISSION_DENIED_FOR_DONATION_ITEMS",
"rel": "information_link",
"method": "GET"
}
]
}
See also
Explore different Orders v2 API use cases.