Error Handling - OpenCart

Error Response Format

When an API request fails, OpenCart returns a JSON response with an error object containing detailed error information.

Standard Error Response

{
  "error": {
    "warning": "General error message describing what went wrong",
    "field_name": "Field-specific error message"
  }
}

Example Error Response

{
  "error": {
    "warning": "Unable to add product to cart",
    "firstname": "First name must be between 1 and 32 characters!",
    "email": "E-Mail address does not appear to be valid!",
    "option_12": "Product option is required!"
  }
}

Error Types

Validation Errors

Errors related to input validation, including length checks, format validation, and required fields.

{
  "error": {
    "firstname": "First name must be between 1 and 32 characters!",
    "lastname": "Last name must be between 1 and 32 characters!",
    "email": "E-Mail address does not appear to be valid!",
    "telephone": "Telephone must be between 3 and 32 characters!"
  }
}

Product Errors

Errors related to product availability, stock, and options.

{
  "error": {
    "warning": "Product not found",
    "product_0_product": "Product does not exist!",
    "product_0_option_5": "Size is required!"
  }
}

Cart Errors

Errors related to cart operations and stock validation.

{
  "error": {
    "warning": "Products marked with *** are not available in the desired quantity or not in stock!",
    "stock": "Product is out of stock"
  }
}

Address Errors

Errors related to address validation.

{
  "error": {
    "payment_firstname": "First name must be between 1 and 32 characters!",
    "payment_address_1": "Address must be between 3 and 128 characters!",
    "payment_city": "City must be between 2 and 128 characters!",
    "payment_postcode": "Postcode must be between 2 and 10 characters!",
    "payment_country": "Please select a country!",
    "payment_zone": "Please select a region / state!"
  }
}

Order Errors

Errors during order confirmation and processing.

{
  "error": {
    "customer": "Customer data is required!",
    "product": "Cart is empty!",
    "payment_address": "Payment address is required!",
    "shipping_address": "Shipping address is required!",
    "shipping_method": "Shipping method is required!",
    "payment_method": "Payment method is required!"
  }
}

Common Error Messages

Customer & Authentication Errors

Error Message	Cause	Solution
`Customer data required`	Customer not set in session	Call customer API to set customer data
`Customer group not found`	Invalid customer group ID	Use valid customer group ID
`Customer does not exist`	Invalid customer ID	Verify customer exists in database

Product & Cart Errors

Error Message	Cause	Solution
`Product does not exist`	Invalid product ID	Verify product ID is correct
`Product is out of stock`	Insufficient stock quantity	Check product quantity availability
`Minimum order quantity is X`	Below minimum quantity	Increase quantity to meet minimum
`Product option is required`	Missing required option	Provide all required product options
`Product option is not valid`	Invalid option value	Use valid option IDs and values

Address Errors

Error Message	Cause	Solution
`First name must be between 1 and 32 characters`	Invalid firstname length	Provide valid firstname
`Address must be between 3 and 128 characters`	Invalid address length	Provide complete address
`Please select a country`	Missing or invalid country	Provide valid country_id
`Please select a region / state`	Missing zone for country	Provide valid zone_id
`Postcode must be between 2 and 10 characters`	Invalid postcode	Provide valid postcode

Order Errors

Error Message	Cause	Solution
`Cart is empty`	No products in cart	Add products before checkout
`Payment address is required`	Missing payment address	Set payment address
`Shipping address is required`	Missing shipping address	Set shipping address
`Shipping method is required`	No shipping method selected	Select shipping method
`Payment method is required`	No payment method selected	Select payment method

Validation Functions

OpenCart uses these validation functions:

Length Validation

oc_validate_length($value, $min, $max)

Validates string length is between min and max characters. Example:

if (!oc_validate_length($firstname, 1, 32)) {
    $error['firstname'] = 'First name must be between 1 and 32 characters!';
}

Email Validation

oc_validate_email($email)

Validates email address format. Example:

if (!oc_validate_email($email)) {
    $error['email'] = 'E-Mail address does not appear to be valid!';
}

Regex Validation

oc_validate_regex($value, $pattern)

Validates value against custom regex pattern. Example:

if (!oc_validate_regex($option_value, $validation_pattern)) {
    $error['option_' . $option_id] = sprintf('Invalid format for %s', $option_name);
}

Error Handling Best Practices

Check for Errors

Always check if the response contains an error key before processing data.

Display Field Errors

Show field-specific errors next to the relevant input fields for better UX.

Log API Errors

Log error responses for debugging and monitoring API issues.

Retry Logic

Implement retry logic for transient errors with exponential backoff.

Example Error Handling

PHP Example

function handleApiResponse($response) {
    $data = json_decode($response, true);
    
    if (isset($data['error'])) {
        // General error
        if (isset($data['error']['warning'])) {
            error_log('API Error: ' . $data['error']['warning']);
        }
        
        // Field-specific errors
        foreach ($data['error'] as $field => $message) {
            if ($field !== 'warning') {
                error_log("Field Error [{$field}]: {$message}");
            }
        }
        
        return false;
    }
    
    if (isset($data['success'])) {
        return $data;
    }
    
    return false;
}

JavaScript Example

function handleApiResponse(response) {
  if (response.data.error) {
    const errors = response.data.error;
    
    // Log general error
    if (errors.warning) {
      console.error('API Error:', errors.warning);
    }
    
    // Display field errors
    Object.keys(errors).forEach(field => {
      if (field !== 'warning') {
        const errorElement = document.querySelector(`#error-${field}`);
        if (errorElement) {
          errorElement.textContent = errors[field];
          errorElement.style.display = 'block';
        }
      }
    });
    
    return false;
  }
  
  if (response.data.success) {
    console.log('Success:', response.data.success);
    return response.data;
  }
  
  return false;
}

HTTP Status Codes

OpenCart API typically returns HTTP 200 status code for all responses. Error detection should be based on the presence of the error key in the JSON response, not HTTP status codes.

Debugging Tips

Enable Error Logging - Check OpenCart error logs for detailed error information
Validate Input Data - Ensure all required fields are provided with correct data types
Check Session State - Verify session contains required data before operations
Test Incrementally - Test each API call individually before chaining operations
Review Source Code - Check controller validation logic for specific requirements

Next Steps

Authentication

Learn about API authentication

Cart API

Explore cart operations

Orders API

Learn order management

Products API

Access product information

​Error Response Format

​Standard Error Response

​Example Error Response

​Error Types

​Common Error Messages

​Customer & Authentication Errors

​Product & Cart Errors

​Address Errors

​Order Errors

​Validation Functions

​Length Validation

​Email Validation

​Regex Validation

​Error Handling Best Practices

Check for Errors

Display Field Errors

Log API Errors

Retry Logic

​Example Error Handling

​PHP Example

​JavaScript Example

​HTTP Status Codes

​Debugging Tips

​Next Steps

Authentication

Cart API

Orders API

Products API

Error Response Format

Standard Error Response

Example Error Response

Error Types

Common Error Messages

Customer & Authentication Errors

Product & Cart Errors

Address Errors

Order Errors

Validation Functions

Length Validation

Email Validation

Regex Validation

Error Handling Best Practices

Example Error Handling

PHP Example

JavaScript Example

HTTP Status Codes

Debugging Tips

Next Steps