Response handling

To handle Cart API responses effectively and provide AI agents with the context they need for intelligent decision-making, understand the status fields and error patterns throughout the cart lifecycle. This guide explains how to interpret cart status indicators, handle validation issues, and implement proper error responses that enable automatic problem resolution.

Note: You can view the complete protocol reference for the Cart API and the Complete Checkout API.

Cart status fields

The PayPal Cart API uses 3 key status indicators that work together to communicate cart state and validation issues.

Field	Description
`status`	Business outcome status (merchant-controlled)
`validation_status`	Validation Status
`validation_issues`	Specific problems with type classification

Note: Understanding these fields is crucial for proper error handling and cart lifecycle management.

Business outcome status

The merchant-controlled status value indicates the current state of the cart.

Value	Description
`CREATED`	Cart was successfully created and is ready for use.
`INCOMPLETE`	Cart has issues that need resolution.
`COMPLETED`	Order is finalized, and payment was captured.

Validation status

The validation_status value indicates whether the cart contents and data are valid for checkout. A valid transaction meets these requirements:

All items are available with current pricing.
Required information is complete (shipping address, customer data, and so on).
No business rule violations exist.
The validation_issues array is empty.

The following table describes the validation-status values.

Value	Description
`VALID`	Cart is ready for checkout.
`INVALID`	Cart has problems that block checkout.
`REQUIRES_ADDITIONAL_INFORMATION`	PayPal requires more data to proceed.

For examples of validation status, see our integration examples.

Validation issues

The validation_issues array communicates business logic problems that prevent cart completion but don’t require HTTP error codes. These structured error objects help AI agents understand what went wrong and how to fix it, whether that’s suggesting alternative products for out-of-stock items, requesting missing information, or explaining pricing changes. Use these patterns to provide clear, actionable feedback that enables automatic resolution or guides customers to make informed decisions.

Field	Available Attributes
`code`	`INVENTORY_ISSUE`, `PRICING_ERROR`, `SHIPPING_ERROR`, `PAYMENT_ERROR`, `DATA_ERROR`, `BUSINESS_RULE_ERROR`
`type`	`MISSING_FIELD`, `INVALID_DATA`, `BUSINESS_RULE`
`message`	`<SPECIFIC VALIDATION MESSAGE>`

Simple validation error (minimal fields)

Here’s the minimum structure for a validation issue with just the required fields:

{
  "code": "INVENTORY_ISSUE",
  "type": "BUSINESS_RULE",
  "message": "Product availability issue"
}

Complete validation error (all fields)

For rich AI agent context, include detailed information and resolution options. Each code can map to a series of specific_issue. More details here.

{
  "code": "INVENTORY_ISSUE",
  "type": "BUSINESS_RULE",
  "message": "Product availability issue",
  "user_message": "The Blue T-Shirt is currently out of stock. Would you like to try a different color?",
  "variant_id": "SHIRT-BLUE-M",
  "context": {
    "specific_issue": "ITEM_OUT_OF_STOCK",
    "available_quantity": 0,
    "requested_quantity": 1,
    "suggested_alternatives": ["SHIRT-RED-M", "SHIRT-GREEN-M"]
  },
  "resolution_options": [
    {
      "action": "SUGGEST_ALTERNATIVE",
      "label": "View similar colors",
      "metadata": { "priority": "high", "auto_applicable": true }
    }
  ]
}

To see examples on validation status, look at our integration example page.

Business logic issues

Use 200 OK for business scenarios that AI agents can understand and potentially resolve:

Cart validation issues (out of stock, price changes)
Missing required information (shipping address, checkout fields)
Payment processing issues (declined payments, business rules)

Technical issues

Use proper HTTP error codes for technical problems. For the complete list of error codes, see HTTP status codes.

Error handling

Effective error handling is critical for maintaining a smooth shopping experience. The API provides rich error context that enables AI agents to resolve issues automatically or guide customers to resolution. Instead of handling dozens of specific error cases, focus on these essential patterns:

Can you fix this automatically? If you can fix it, fix it for them.
Can the customer fix this? If you can’t fix it for them, show them how to fix it.

Error categories

Category	Description
`INVENTORY_ISSUE`	Stock, availability, back-orders, discontinued items
`PRICING_ERROR`	Price changes, discounts, tax calculation, currency issues
`SHIPPING_ERROR`	Address validation, delivery restrictions, shipping zones
`PAYMENT_ERROR`	Payment limits, currency support, processor issues
`DATA_ERROR`	Field validation, format issues, required fields
`BUSINESS_RULE_ERROR`	Account restrictions, compliance, regional limits

Error types

Type	Description
`MISSING_FIELD`	Need more info (address, checkout fields)
`INVALID_DATA`	Data validation failed
`BUSINESS_RULE`	Business logic violation, such as inventory issues

Common error pattern

Most validation errors follow this structure with clear user messaging and actionable options:

{
  "code": "INVENTORY_ISSUE",
  "user_message": "Blue T-Shirt is out of stock. Try a different color?",
  "resolution_options": [
    {
      "action": "SUGGEST_ALTERNATIVE",
      "label": "View other colors"
    },
    {
      "action": "REMOVE_ITEM",
      "label": "Remove from cart"
    }
  ]
}

Error handling implementation strategy

When implementing error handling for the PayPal Cart API, use the following guidelines to determine appropriate HTTP status codes and error responses.

200 OK + validation_issues

Inventory changes (out of stock, back-ordered)
Price changes during checkout
Payment processing issues that can be resolved
Geographic restrictions
Discount validation failures
Customer account issues
Address validation problems

422 Unprocessable entity

Use this error code when any validation_issue prevents you from creating a cart. For example, if you do not create a cart for an OUT_OF_STOCK issue, you can send a 422 Unprocessable Entity error with details about the error in the body.

400 Bad request

Invalid JSON format
Missing required fields (for example, the items array)
Invalid field types or formats
Malformed request structure
Invalid cart ID format (for example, it doesn’t match an expected pattern, such as "CART-[A-Z0-9]+")

404 not found

Cart ID doesn’t exist in merchant’s system (well-formed ID but not found)
Invalid endpoint paths

Cart retrieval error handling

These examples use GET /merchant-cart/{cartId}. Example: Invalid cart ID format (400 response) When the cart ID doesn’t match your expected format, return detailed validation information.

{
  "name": "INVALID_CART_ID",
  "message": "Cart ID format is invalid. Expected format: CART-[A-Z0-9]+",
  "debug_id": "ERROR-400-CART-FORMAT",
  "details": [
    {
      "field": "cartId",
      "issue": "INVALID_FORMAT",
      "description": "Cart ID format is invalid. Expected format: CART-[A-Z0-9]+. Provided: invalid-cart-id-123"
    }
  ]
}

Example: Cart not found (404 response) When a well-formed cart ID doesn’t exist in your system, provide clear guidance.

{
  "name": "CART_NOT_FOUND",
  "message": "Cart with ID 'CART-MISSING-123' does not exist",
  "debug_id": "ERROR-404-12345",
  "details": [
    {
      "field": "cartId",
      "issue": "NOT_FOUND",
      "description": "Cart with ID 'CART-MISSING-123' does not exist for merchant 'MERCHANT_789'. Verify cart ID or create a new cart."
    }
  ]
}

500 internal server error

System failures
Database connectivity issues
Payment processor unavailable
Unexpected server errors

Error context best practices

Provide rich context: Include all relevant information for smart resolution.
Customer-friendly messages: Write user_message for end customers.
Technical details: Include technical message for developers.
Resolution guidance: Always provide actionable next steps.
Cost impact: Show financial implications of resolution options.
Time estimates: Provide realistic timeframes for resolutions.

AI agent considerations for errors

Many errors are well-suited for AI agents to handle autonomously:

Auto-applicable actions: AI can resolve without human intervention.
Priority guidance: Immediate action is required.
Context-rich: The system has enough information for intelligent decision making.
Resolution metadata: The system helps AI choose the best resolution.

Resolution action types

Action	Use Case	Auto-applicable
`ACCEPT_NEW_PRICE`	Price increases	No
`ACCEPT_BACK_ORDER`	Inventory delays	Depends on customer preference
`SUGGEST_ALTERNATIVE`	Out of stock items	Yes
`UPDATE_ADDRESS`	Address validation	Yes (if correction available)
`REMOVE_ITEM`	Restriction violations	Depends on item importance
`SPLIT_ORDER`	Payment limits	Yes
`CONTACT_SUPPORT`	Complex issues	No
`RETRY_LATER`	Temporary failures	Yes

Next steps

Continue by looking at integration examples.

Grow your business

Send payouts

Manage disputes

Analyze reports

Agentic commerce

Cart status fields

Business outcome status

Validation status

Validation issues

Simple validation error (minimal fields)

Complete validation error (all fields)

Business logic issues

Technical issues

Error handling

Error categories

Error types

Common error pattern

Error handling implementation strategy

200 OK + validation_issues

422 Unprocessable entity

400 Bad request

404 not found

Cart retrieval error handling

500 internal server error

Error context best practices

AI agent considerations for errors

Resolution action types

Next steps

Grow your business

Send payouts

Manage disputes

Analyze reports

Agentic commerce

​Cart status fields

​Business outcome status

​Validation status

​Validation issues

​Simple validation error (minimal fields)

​Complete validation error (all fields)

​Business logic issues

​Technical issues

​Error handling

​Error categories

​Error types

​Common error pattern

​Error handling implementation strategy

​200 OK + validation_issues

​422 Unprocessable entity

​400 Bad request

​404 not found

​Cart retrieval error handling

​500 internal server error

​Error context best practices

​AI agent considerations for errors

​Resolution action types

​Next steps

Cart status fields

Business outcome status

Validation status

Validation issues

Simple validation error (minimal fields)

Complete validation error (all fields)

Business logic issues

Technical issues

Error handling

Error categories

Error types

Common error pattern

Error handling implementation strategy

200 OK + validation_issues

422 Unprocessable entity

400 Bad request

404 not found

Cart retrieval error handling

500 internal server error

Error context best practices

AI agent considerations for errors

Resolution action types

Next steps