Error Handling

The Chariow API uses conventional HTTP response codes to indicate the success or failure of requests.

Response Format

All API responses follow a consistent format:

{
  "message": "Success message or error description",
  "data": {},
  "errors": []
}

HTTP Status Codes

Code	Description
`200`	Success - Request completed successfully
`201`	Created - Resource created successfully
`400`	Bad Request - Invalid request parameters
`401`	Unauthorised - Invalid or missing API key
`403`	Forbidden - Access denied to this resource
`404`	Not Found - Resource doesn’t exist
`422`	Unprocessable Entity - Validation failed
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error - Something went wrong

Common Errors

Authentication Errors (401)

{
  "message": "Store API key is required",
  "data": [],
  "errors": []
}

Causes:

Missing Authorization header
Invalid API key format
Revoked or expired API key

Solution:

# Ensure you include the Authorization header
curl -X GET "https://api.chariow.com/v1/store" \
  -H "Authorization: Bearer sk_live_your_api_key"

Resource Not Found (404)

{
  "message": "No query results for model [App\\Models\\Product].",
  "data": [],
  "errors": []
}

Causes:

Invalid resource ID
Resource belongs to a different store
Resource has been deleted
Product is not published (for public endpoints)

Validation Errors (422)

{
  "message": "The given data was invalid.",
  "data": [],
  "errors": {
    "email": ["The email field is required."],
    "product_id": ["The selected product_id is invalid."]
  }
}

Causes:

Missing required fields
Invalid field format
Business rule violations

Rate Limit Exceeded (429)

{
  "message": "Rate limit exceeded. Please retry after 60 seconds.",
  "data": [],
  "errors": []
}

Solution: Wait for the specified time and retry. See Rate Limits for details.

Handling Errors

JavaScript Example

async function makeRequest(endpoint, options = {}) {
  const response = await fetch(`https://api.chariow.com/v1${endpoint}`, {
    ...options,
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
      ...options.headers
    }
  });

  const data = await response.json();

  if (!response.ok) {
    switch (response.status) {
      case 401:
        throw new AuthenticationError(data.message);
      case 404:
        throw new NotFoundError(data.message);
      case 422:
        throw new ValidationError(data.message, data.errors);
      case 429:
        throw new RateLimitError(data.message);
      default:
        throw new ApiError(data.message, response.status);
    }
  }

  return data;
}

// Usage
try {
  const product = await makeRequest('/products/prd_abc123');
  console.log(product);
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log('Product not found');
  } else if (error instanceof ValidationError) {
    console.log('Validation failed:', error.errors);
  } else {
    console.error('API error:', error.message);
  }
}

PHP Example

<?php

function makeRequest($endpoint, $method = 'GET', $data = null) {
    $ch = curl_init();

    curl_setopt($ch, CURLOPT_URL, "https://api.chariow.com/v1{$endpoint}");
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer ' . getenv('CHARIOW_API_KEY'),
        'Content-Type: application/json'
    ]);

    if ($method === 'POST') {
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    }

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    $result = json_decode($response, true);

    if ($httpCode >= 400) {
        throw new Exception($result['message'], $httpCode);
    }

    return $result;
}

// Usage
try {
    $product = makeRequest('/products/prd_abc123');
    print_r($product);
} catch (Exception $e) {
    if ($e->getCode() === 404) {
        echo "Product not found\n";
    } else {
        echo "API error: " . $e->getMessage() . "\n";
    }
}

Error Codes Reference

Checkout Errors

Message	Cause	Solution
`Product not found`	Invalid product ID or unpublished	Use a valid, published product ID
`Already purchased`	Customer owns this product	Redirect to their purchase
`Product unavailable`	Out of stock or quantity limit	Check product availability
`Invalid discount code`	Code doesn’t exist or expired	Verify the discount code

License Errors

Message	Cause	Solution
`License not found`	Invalid license key	Verify the license key
`License already activated`	Reached activation limit	Show user their activations
`License expired`	Past expiration date	Prompt for renewal
`License revoked`	Manually revoked	Contact support

Best Practices

Always Check Status Codes

Don’t assume success - always check the HTTP status code before processing the response.

Log Errors

Log error responses for debugging and monitoring purposes.

Show User-Friendly Messages

Translate API errors into user-friendly messages for your customers.

Implement Retry Logic

For 5xx errors and rate limits, implement automatic retry with exponential backoff.

Introduction

Guides

Resources

MCP Integration

Response Format

HTTP Status Codes

Common Errors

Authentication Errors (401)

Resource Not Found (404)

Validation Errors (422)

Rate Limit Exceeded (429)

Handling Errors

JavaScript Example

PHP Example

Error Codes Reference

Checkout Errors

License Errors

Best Practices

Introduction

Guides

Resources

MCP Integration

​Response Format

​HTTP Status Codes

​Common Errors

​Authentication Errors (401)

​Resource Not Found (404)

​Validation Errors (422)

​Rate Limit Exceeded (429)

​Handling Errors

​JavaScript Example

​PHP Example

​Error Codes Reference

​Checkout Errors

​License Errors

​Best Practices

Response Format

HTTP Status Codes

Common Errors

Authentication Errors (401)

Resource Not Found (404)

Validation Errors (422)

Rate Limit Exceeded (429)

Handling Errors

JavaScript Example

PHP Example

Error Codes Reference

Checkout Errors

License Errors

Best Practices