Error Handling

This guide explains how to handle errors from the CLE Engine API.

HTTP Status Codes

Error Response Format

All error responses follow a consistent JSON structure:

{
  "detail": "Error message describing what went wrong"
}

Authentication Errors (401)

Invalid API Key

Request:

curl -X POST https://api.cle-engine.com/v1/compute \
  -H "Content-Type: application/json" \
  -H "X-API-Key: invalid_key" \
  -d '{"jurisdiction": "CA"}'

Response:

{
  "detail": "invalid api key"
}

Causes:

• API key is malformed (doesn't start with cle_)
• API key doesn't exist in the system
• API key was deleted or regenerated

Solution:

1. Verify your API key starts with cle_
2. Retrieve your current API key from the dashboard
3. Ensure you're using the complete key (36 characters after prefix)

Missing API Key

Request:

curl -X POST https://api.cle-engine.com/v1/compute \
  -H "Content-Type: application/json" \
  -d '{"jurisdiction": "CA"}'

Response:

{
  "detail": "API key required"
}

Solution: Add the X-API-Key header to your request.

Inactive API Key

Response:

{
  "detail": "api key inactive"
}

Causes:

• API key was disabled in the dashboard
• Account was suspended
• Subscription expired

Solution:

1. Check your account status in the dashboard
2. Reactivate the API key or create a new one
3. Verify your subscription is active

Rate Limit Errors (429)

Quota Exceeded

Response:

{
  "detail": "quota exceeded"
}

Causes:

• Monthly request quota reached
• Unusual spike in API usage

Solution:

1. Check your current usage in the dashboard
2. Wait for the quota to reset (monthly)
3. Upgrade to a higher tier for more requests

Tier Limits

Validation Errors (422)

Invalid Request Body

Request:

curl -X POST https://api.cle-engine.com/v1/compute \
  -H "Content-Type: application/json" \
  -H "X-API-Key: cle_your_key" \
  -d 'invalid json'

Response:

{
  "detail": [
    {
      "type": "json_invalid",
      "loc": ["body"],
      "msg": "Invalid JSON"
    }
  ]
}

Invalid Date Format

Request:

curl -X POST https://api.cle-engine.com/v1/compute \
  -H "Content-Type: application/json" \
  -H "X-API-Key: cle_your_key" \
  -d '{"jurisdiction": "CO", "admission_date": "June 15, 2020"}'

Response:

{
  "detail": [
    {
      "type": "date_parsing",
      "loc": ["body", "admission_date"],
      "msg": "Input should be a valid date"
    }
  ]
}

Solution: Use ISO 8601 date format: YYYY-MM-DD

Missing Required Field

Request:

curl -X POST https://api.cle-engine.com/v1/compute \
  -H "Content-Type: application/json" \
  -H "X-API-Key: cle_your_key" \
  -d '{}'

Response:

{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "jurisdiction"],
      "msg": "Field required"
    }
  ]
}

Server Errors (500)

Internal Server Error

Response:

{
  "detail": "Internal server error"
}

Causes:

• Unexpected server-side issue
• Database connectivity problem
• Deployment in progress

Solution:

1. Retry the request after a few seconds
2. Check the status page for outages
3. Contact support if the issue persists

Successful Responses with Missing Data

Not all "successful" responses contain complete data. Check for missing_fields:

{
  "due_date": null,
  "missing_fields": ["last_name"],
  "notes": "Missing required fields for due date calculation: last_name."
}

This is a 200 OK response, but indicates you need to provide additional data.

Best Practices for Error Handling

1. Always Check Status Codes

import requests

response = requests.post(
    "https://api.cle-engine.com/v1/compute",
    headers={"X-API-Key": api_key},
    json={"jurisdiction": "CA", "last_name": "Smith"}
)

if response.status_code == 200:
    data = response.json()
    # Process successful response
elif response.status_code == 401:
    print("Authentication failed. Check your API key.")
elif response.status_code == 429:
    print("Rate limit exceeded. Please wait or upgrade your plan.")
else:
    print(f"Error: {response.status_code} - {response.text}")

2. Handle Missing Fields

data = response.json()

if data.get("missing_fields"):
    missing = ", ".join(data["missing_fields"])
    print(f"Cannot calculate deadline. Please provide: {missing}")
else:
    print(f"Due date: {data['due_date']}")

3. Implement Retry Logic

import time
import requests

def make_request(url, headers, json_data, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(url, headers=headers, json=json_data)

        if response.status_code == 200:
            return response.json()
        elif response.status_code == 429:
            wait_time = 2 ** attempt  # Exponential backoff
            print(f"Rate limited. Waiting {wait_time} seconds...")
            time.sleep(wait_time)
        elif response.status_code >= 500:
            wait_time = 2 ** attempt
            print(f"Server error. Retrying in {wait_time} seconds...")
            time.sleep(wait_time)
        else:
            # Client error - don't retry
            raise Exception(f"API error: {response.status_code}")

    raise Exception("Max retries exceeded")

4. Log Errors for Debugging

import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

try:
    response = make_api_request()
    if response.status_code != 200:
        logger.error(
            f"API request failed: status={response.status_code}, "
            f"body={response.text}, "
            f"request_id={response.headers.get('X-Request-ID')}"
        )
except Exception as e:
    logger.exception("Unexpected error during API request")

Troubleshooting Checklist

Getting Help

If you encounter persistent errors:

1. Check the status page
2. Review the API documentation
3. Search GitHub Issues
4. Contact support at support@cle-engine.com with:
   • Your request details (redact API key)
   • The full error response
   • Timestamp of the error