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": []
}

Error responses always carry message and errors. Some of them, such as authentication and rate limit errors, omit the data field.

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 - The API key lacks a scope the endpoint requires
`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": "API key is missing. Please provide a valid API key. Help: https://docs.chariow.com",
  "errors": []
}

Message	Cause
`API key is missing. Please provide a valid API key. Help: https://docs.chariow.com`	Missing `Authorization: Bearer` header
`Invalid API key. Please check again. Help: https://docs.chariow.com`	Malformed or deleted key, or a key whose creator is no longer an active team member

Solution:

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

Missing Scope (403)

The API key is valid but lacks a scope the endpoint requires:

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope", scope="checkout.write"

{
  "message": "This credential is missing the required scope: checkout.write. Update its permissions in your dashboard.",
  "data": [],
  "errors": {
    "scopes": ["checkout.write"]
  }
}

Causes:

The key was created without the scope the endpoint requires
The role of the team member who created the key was downgraded, which removed the scope

Solution: Add the scopes listed in errors.scopes to the key in Settings → API Keys. Read errors.scopes rather than message in your code, because the message is translated into the request language. See Authentication for the scope each endpoint requires.

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 email field is required. (and 1 more error)",
  "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": "Too Many Attempts.",
  "errors": []
}

Solution: Wait for the number of seconds given in the Retry-After header 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 403:
        throw new MissingScopeError(data.message, data.errors.scopes);
      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. Please verify the product ID and ensure it is published.`	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 key not found.`	Invalid license key	Verify the license key
`Activation limit reached`	All activations are used	Show user their activations
`License has expired`	Past expiration date	Prompt for renewal
`License has been revoked`	Manually revoked	Contact support
`License has already been revoked`	Revoking a licence that is already revoked	No action needed

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

MCP Integration

n8n Integration

Resources

Response Format

HTTP Status Codes

Common Errors

Authentication Errors (401)

Missing Scope (403)

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)

​Missing Scope (403)

​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)

Missing Scope (403)

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