Error Handling

Learn how to handle errors in the ACOD Cash on Delivery API. This guide explains our error format, common error codes, and best practices for error handling in your Shopify integration.

Error Response Format

All API errors follow a consistent format:

{
  "error": {
    "code": "invalid_request",
    "message": "A human-readable error message",
    "details": {
      // Additional error context (optional)
    },
    "request_id": "req_123abc"
  }
}

HTTP Status Codes

The API uses standard HTTP status codes to indicate the success or failure of a request:

2xx - Success

• 200 OK - Request succeeded
• 201 Created - Resource was successfully created
• 204 No Content - Request succeeded with no response body

4xx - Client Errors

• 400 Bad Request - Invalid request format or parameters
• 401 Unauthorized - Missing or invalid authentication
• 403 Forbidden - Valid authentication but insufficient permissions
• 404 Not Found - Requested resource doesn't exist
• 422 Unprocessable Entity - Valid request but failed business logic
• 429 Too Many Requests - Rate limit exceeded

5xx - Server Errors

• 500 Internal Server Error - Unexpected server error
• 503 Service Unavailable - Service temporarily unavailable

Common Error Codes

These are the most common error codes you might encounter in COD fee calculations:

// Authentication Errors
invalid_api_key         // The API key is invalid or expired
missing_api_key         // No API key was provided
invalid_shop_domain     // The Shopify store domain is invalid or not associated with your API key

// COD Fee Calculation Errors
invalid_request         // The request format is invalid
missing_cart_total      // Cart total is required for fee calculation
invalid_currency        // Unsupported currency for COD fees
missing_shipping_address // Shipping address is required for location-based fees
cod_not_available       // COD is not available for the given location/cart/items

// Resource Errors
rule_not_found          // The requested fee rule was not found
location_group_not_found // The requested location group was not found
invalid_fee_structure   // The fee structure is invalid or inconsistent

// Permission Errors
unauthorized            // Authentication required
forbidden               // Insufficient permissions for the operation
rate_limited            // Too many requests

// Server Errors
internal_error          // Unexpected server error
service_unavailable     // Service is temporarily unavailable

Error Handling Best Practices

Here are some recommended practices for handling API errors in your Shopify integration:

1. Always Check Status Codes

async function calculateCodFee(cart, address) {
  try {
    const response = await fetch('https://api.acod.app/v1/calculate-fee', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${ACOD_API_KEY}`,
        'Content-Type': 'application/json',
        'X-Shopify-Shop-Domain': shopDomain
      },
      body: JSON.stringify({ cart_total: cart.total, shipping_address: address })
    });
    
    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.error.message);
    }
    
    return await response.json();
  } catch (error) {
    // Handle error appropriately
    console.error('ACOD API Error:', error);
    return { cod_fee: 0, is_cod_available: false };
  }
}

2. Implement Retry Logic

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, options);
      if (response.status !== 503) return response;
      
      // Wait before retrying (exponential backoff)
      await new Promise(resolve => 
        setTimeout(resolve, Math.pow(2, i) * 1000)
      );
    } catch (error) {
      if (i === maxRetries - 1) throw error;
    }
  }
}

Rate Limiting

When you exceed the rate limit, you'll receive a 429 Too Many Requests response with these headers:

X-RateLimit-Limit: 500 X-RateLimit-Remaining: 0 X-RateLimit-Reset: 1640995200

Next Steps

• Review the API Endpoints documentation for COD fee calculation
• Learn about API Authentication for secure Shopify integration
• Explore Advanced Fee Conditions for complex COD rules