Canonical URL: https://chargezen.com/docs/checkoutos/troubleshooting/error-codes

# Error Codes

Reference guide for CheckoutOS error codes and their solutions

Last updated: 2025-01-16

This reference covers error codes you may encounter when using CheckoutOS. Each error includes its meaning and recommended resolution steps.

##### Finding Error Codes

Error codes appear in the CheckoutOS dashboard notifications, browser console, and webhook responses. Look for codes in the format `COS-XXXX`.

## Installation Errors (COS-1XXX)

### COS-1001: Shopify Connection Failed

**Cause:** Unable to establish connection with your Shopify store.

**Solutions:**

*   Verify your Shopify store URL is correct
*   Check that your Shopify store is active (not paused or on hold)
*   Reinstall the CheckoutOS app from the Shopify App Store
*   Ensure you have admin or owner permissions on the Shopify store

### COS-1002: Permission Denied

**Cause:** CheckoutOS doesn't have required permissions.

**Solutions:**

*   Reinstall the app to re-authorize permissions
*   Verify you're logged in as a store owner or admin
*   Check Shopify Admin → Apps → CheckoutOS for permission status

### COS-1003: Checkout Extensibility Not Available

**Cause:** Your Shopify plan doesn't support checkout extensions.

**Solutions:**

*   Upgrade to Shopify Plus for full checkout extensibility
*   Apply for Checkout Extensibility beta access (non-Plus stores)
*   Use post-purchase features only (available on all plans)

## Campaign Errors (COS-2XXX)

### COS-2001: Invalid Campaign Configuration

**Cause:** Campaign has missing or invalid settings.

**Solutions:**

*   Review all required campaign fields
*   Ensure at least one product is selected for upsell
*   Check that discount values are within valid ranges

Valid Campaign Structure

```json
{
  "name": "Summer Upsell",
  "active": true,
  "products": ["gid://shopify/Product/123"],
  "discount": {
    "type": "percentage",
    "value": 20
  },
  "targeting": {
    "minCartValue": 50
  }
}
```

### COS-2002: Product Not Found

**Cause:** A product in your campaign no longer exists or is unavailable.

**Solutions:**

*   Check if the product was deleted from your Shopify catalog
*   Verify the product is published and active
*   Update the campaign with valid product IDs

### COS-2003: Targeting Rule Conflict

**Cause:** Campaign targeting rules contradict each other.

**Solutions:**

*   Review AND/OR logic in targeting rules
*   Ensure minimum and maximum values don't overlap incorrectly
*   Check for impossible conditions (e.g., cart > $100 AND cart < $50)

## Checkout Errors (COS-3XXX)

### COS-3001: Discount Application Failed

**Cause:** Unable to apply discount to upsell product.

**Solutions:**

*   Check for conflicting Shopify discount codes
*   Verify discount combination settings in Shopify
*   Ensure the product isn't excluded from discounts

### COS-3002: Payment Processing Error

**Cause:** Unable to charge customer for upsell product.

**Solutions:**

*   This is typically a Shopify payment gateway issue
*   Check Shopify Admin → Settings → Payments for gateway status
*   Customer may need to retry with a different payment method

##### Payment Errors

CheckoutOS never stores payment information. Payment errors are processed through Shopify's secure payment infrastructure. Check Shopify for detailed payment logs.

### COS-3003: Inventory Unavailable

**Cause:** Upsell product is out of stock.

**Solutions:**

*   Enable inventory tracking fallbacks in campaign settings
*   Set up backup products for out-of-stock scenarios
*   Configure "Continue selling when out of stock" in Shopify if appropriate

## API Errors (COS-4XXX)

### COS-4001: Invalid API Key

**Cause:** API request used an invalid or expired key.

**Solutions:**

*   Regenerate API key in Dashboard → Settings → API
*   Check for typos or whitespace in the key
*   Ensure the key has required permissions

### COS-4002: Rate Limit Exceeded

**Cause:** Too many API requests in a short period.

**Solutions:**

*   Implement request throttling in your application
*   Use webhook events instead of polling
*   Contact support if you need higher rate limits

Rate Limit Headers

```text
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1642345678
Retry-After: 60
```

### COS-4003: Invalid Webhook Signature

**Cause:** Webhook signature verification failed.

**Solutions:**

*   Verify webhook secret matches Dashboard → Settings → API
*   Ensure you're using the raw request body for signature verification
*   Check that your server clock is synchronized

## Extension Errors (COS-5XXX)

### COS-5001: Extension Failed to Load

**Cause:** Checkout extension couldn't load in the browser.

**Solutions:**

*   Check browser console for JavaScript errors
*   Disable ad blockers or privacy extensions temporarily
*   Clear browser cache and try again
*   Test in a different browser

### COS-5002: Extension Render Error

**Cause:** Extension loaded but couldn't render properly.

**Solutions:**

*   Check for custom CSS conflicts
*   Verify image URLs are valid and accessible
*   Review extension configuration for invalid settings

## Need More Help?

[

### FAQ

Answers to frequently asked questions

Learn more



](https://chargezen.com/docs/checkoutos/troubleshooting/faq)[

### Contact Support

Get personalized help from our team

Learn more



](https://chargezen.com/docs/checkoutos/troubleshooting/support)

Was this page helpful?

Need more help? [Contact support](https://chargezen.com/docs/checkoutos/troubleshooting/support)