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

Copy
Copied
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

Copy
Copied
{
  "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

Copy
Copied
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

Copy
Copied
{
    "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

Copy
Copied
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

Copy
Copied
{
  "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

Copy
Copied
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

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