Error Codes & Responses

Error Response Format

All API errors follow a consistent JSON structure to make error handling predictable:

Error Response Structure

{
  "status": "error",
  "error": "Brief error description",
  "message": "Human-readable error details",
  "code": "MACHINE_READABLE_CODE",
  "details": {
    "field": "Additional context when applicable"
  }
}

string

Always “error” for error responses

string

Brief, human-readable error summary

string

Detailed error description with actionable guidance

string

Machine-readable error code for programmatic handling

object

Additional context specific to the error (optional)

HTTP Status Codes

400 Bad Request

Invalid request format, missing required fields, or invalid parameters

401 Unauthorized

Authentication failed - invalid or missing API key

403 Forbidden

Valid authentication but insufficient permissions

404 Not Found

Endpoint or resource doesn’t exist

429 Too Many Requests

Rate limit exceeded - too many requests in time window

500 Internal Server Error

Unexpected server error - contact support if persistent

Authentication Errors

INVALID_API_KEY - Invalid or malformed API key

{
  "status": "error",
  "error": "Invalid API key",
  "message": "The provided API key is invalid or has been revoked",
  "code": "INVALID_API_KEY"
}

Common Causes:

API key doesn’t start with ap_
Typo in API key
API key has been revoked
Using wrong environment’s key

Solutions:

Verify API key format and spelling
Generate a new API key from your dashboard
Ensure you’re using the correct environment

MISSING_AUTH_HEADER - Authorization header missing

{
  "status": "error",
  "error": "Missing authorization",
  "message": "Authorization header is required",
  "code": "MISSING_AUTH_HEADER"
}

Common Causes:

Forgot to include Authorization header
Header name is incorrect (should be Authorization)
Missing “Bearer ” prefix

Solutions:

Add Authorization: Bearer ap_your_key_here header
Check header spelling and format

EXPIRED_API_KEY - API key has expired

{
  "status": "error",
  "error": "API key expired",
  "message": "Your API key has expired. Please generate a new one",
  "code": "EXPIRED_API_KEY"
}

Solutions:

Generate a new API key from your dashboard
Update your application with the new key
Set up key rotation reminders

Rate Limiting Errors

RATE_LIMIT_EXCEEDED - Too many requests

{
  "status": "error",
  "error": "Rate limit exceeded",
  "message": "You have exceeded your rate limit of 60 requests per minute. Please try again in 23 seconds.",
  "code": "RATE_LIMIT_EXCEEDED",
  "retry_after": 23
}

Response Headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1708185623
Retry-After: 23

Solutions:

Wait for the time specified in retry_after
Implement exponential backoff
Upgrade to a higher plan for increased limits
Use multiple API keys to distribute load

Request Validation Errors

MISSING_REQUIRED_FIELD - Required parameter missing

{
  "status": "error",
  "error": "Missing required field",
  "message": "The 'domain' field is required but was not provided",
  "code": "MISSING_REQUIRED_FIELD",
  "details": {
    "field": "domain",
    "required_fields": ["domain", "topic", "country"]
  }
}

Solutions:

Check API documentation for required fields
Ensure all required parameters are included
Verify request body structure

INVALID_FIELD_FORMAT - Field format is incorrect

{
  "status": "error",
  "error": "Invalid field format",
  "message": "Country code must be a 2-letter ISO code (e.g., 'US', 'UK')",
  "code": "INVALID_FIELD_FORMAT",
  "details": {
    "field": "country",
    "provided_value": "USA",
    "expected_format": "2-letter ISO code"
  }
}

Solutions:

Check the expected format in API documentation
Validate input data before making requests
Use proper data types and formats

INVALID_DOMAIN_FORMAT - Domain format incorrect

{
  "status": "error",
  "error": "Invalid domain format",
  "message": "Domain must be in format 'example.com' without protocol or path",
  "code": "INVALID_DOMAIN_FORMAT",
  "details": {
    "field": "domain",
    "provided_value": "https://example.com/blog",
    "expected_format": "example.com"
  }
}

Solutions:

Remove protocol (http://, https://)
Remove paths, subdomains (www.), ports
Use just the root domain: example.com

Business Logic Errors

INSUFFICIENT_CREDITS - Not enough credits

{
  "status": "error",
  "error": "Insufficient credits",
  "message": "This request requires 15 credits but you only have 8 remaining",
  "code": "INSUFFICIENT_CREDITS",
  "details": {
    "required_credits": 15,
    "available_credits": 8,
    "upgrade_url": "https://platform.agenticpencil.com/billing"
  }
}

Solutions:

Wait for next billing cycle (free/monthly plans)
Upgrade to a higher plan
Monitor credit usage with /v1/usage endpoint

DOMAIN_NOT_FOUND - Domain cannot be analyzed

{
  "status": "error",
  "error": "Domain not found",
  "message": "Unable to analyze domain 'nonexistent-domain.xyz' - domain may not exist or be accessible",
  "code": "DOMAIN_NOT_FOUND",
  "details": {
    "domain": "nonexistent-domain.xyz"
  }
}

Solutions:

Verify the domain exists and is accessible
Check for typos in domain name
Ensure domain has sufficient content to analyze
Try again later if domain is temporarily unavailable

SITEMAP_NOT_FOUND - Sitemap inaccessible

{
  "status": "error",
  "error": "Sitemap not found",
  "message": "Could not find or access sitemap at 'https://example.com/sitemap.xml'",
  "code": "SITEMAP_NOT_FOUND",
  "details": {
    "sitemap_url": "https://example.com/sitemap.xml",
    "attempted_locations": [
      "https://example.com/sitemap.xml",
      "https://example.com/sitemap_index.xml",
      "https://example.com/robots.txt"
    ]
  }
}

Solutions:

Verify sitemap URL is correct and accessible
Check robots.txt for sitemap location
Ensure sitemap is publicly accessible (not behind authentication)
Omit sitemap_url to let us auto-discover it

Plan and Billing Errors

PLAN_LIMIT_EXCEEDED - Plan feature limit reached

{
  "status": "error",
  "error": "Plan limit exceeded",
  "message": "Your Free plan allows maximum 10 keywords per request. Upgrade to Pro for up to 100 keywords.",
  "code": "PLAN_LIMIT_EXCEEDED",
  "details": {
    "current_plan": "free",
    "limit_type": "keywords_per_request",
    "current_limit": 10,
    "requested": 25,
    "upgrade_plans": ["pro", "scale"]
  }
}

Solutions:

Reduce request size to fit plan limits
Upgrade to a higher plan
Split large requests into multiple smaller ones

SUBSCRIPTION_REQUIRED - Paid plan needed

{
  "status": "error",
  "error": "Subscription required",
  "message": "This feature requires a paid subscription. Please upgrade to Pro or Scale plan.",
  "code": "SUBSCRIPTION_REQUIRED",
  "details": {
    "required_plans": ["pro", "scale", "enterprise"],
    "current_plan": "free"
  }
}

Solutions:

Upgrade to a paid plan
Use alternative endpoints available on your plan

Server Errors

INTERNAL_SERVER_ERROR - Unexpected server error

{
  "status": "error",
  "error": "Internal server error",
  "message": "An unexpected error occurred. Our team has been notified. Please try again later.",
  "code": "INTERNAL_SERVER_ERROR",
  "details": {
    "incident_id": "inc_1234567890abcdef",
    "timestamp": "2024-02-17T17:10:32Z"
  }
}

Solutions:

Try the request again after a short delay
Contact support with the incident_id if problem persists
Check our status page for known issues

SERVICE_UNAVAILABLE - Temporary service disruption

{
  "status": "error",
  "error": "Service temporarily unavailable",
  "message": "The service is temporarily unavailable due to maintenance. Please try again in a few minutes.",
  "code": "SERVICE_UNAVAILABLE",
  "details": {
    "retry_after": 300,
    "maintenance_window": "2024-02-17T18:00:00Z - 2024-02-17T18:30:00Z"
  }
}

Solutions:

Wait for the specified retry_after time
Check our status page for maintenance schedules
Implement retry logic with exponential backoff

Error Handling Best Practices

1. Implement Proper Error Handling

import requests
import time

def handle_api_call(url, headers, data, max_retries=3):
    for attempt in range(max_retries + 1):
        try:
            response = requests.post(url, headers=headers, json=data)
            
            # Handle success
            if response.status_code == 200:
                return response.json()
            
            # Parse error response
            error_data = response.json()
            error_code = error_data.get('code')
            
            # Handle specific errors
            if error_code == 'RATE_LIMIT_EXCEEDED':
                retry_after = error_data.get('retry_after', 60)
                if attempt < max_retries:
                    print(f"Rate limited, retrying after {retry_after} seconds")
                    time.sleep(retry_after)
                    continue
                    
            elif error_code == 'INSUFFICIENT_CREDITS':
                print("❌ Insufficient credits - please upgrade your plan")
                return None
                
            elif error_code in ['INVALID_API_KEY', 'EXPIRED_API_KEY']:
                print("❌ Authentication error - check your API key")
                return None
                
            elif error_code == 'INTERNAL_SERVER_ERROR':
                if attempt < max_retries:
                    delay = 2 ** attempt  # Exponential backoff
                    print(f"Server error, retrying in {delay} seconds")
                    time.sleep(delay)
                    continue
            
            # For other errors, don't retry
            print(f"❌ API Error: {error_data.get('message')}")
            return None
            
        except requests.RequestException as e:
            if attempt == max_retries:
                print(f"❌ Request failed: {e}")
                return None
                
            time.sleep(2 ** attempt)
    
    return None

const axios = require('axios');

async function handleApiCall(url, config, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      const response = await axios.post(url, config.data, {
        headers: config.headers
      });
      
      return response.data;
      
    } catch (error) {
      if (error.response) {
        const errorData = error.response.data;
        const errorCode = errorData.code;
        
        switch (errorCode) {
          case 'RATE_LIMIT_EXCEEDED':
            if (attempt < maxRetries) {
              const retryAfter = errorData.retry_after || 60;
              console.log(`Rate limited, retrying after ${retryAfter} seconds`);
              await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
              continue;
            }
            break;
            
          case 'INSUFFICIENT_CREDITS':
            console.error('❌ Insufficient credits - please upgrade your plan');
            return null;
            
          case 'INVALID_API_KEY':
          case 'EXPIRED_API_KEY':
            console.error('❌ Authentication error - check your API key');
            return null;
            
          case 'INTERNAL_SERVER_ERROR':
            if (attempt < maxRetries) {
              const delay = Math.pow(2, attempt) * 1000;
              console.log(`Server error, retrying in ${delay/1000} seconds`);
              await new Promise(resolve => setTimeout(resolve, delay));
              continue;
            }
            break;
        }
        
        console.error(`❌ API Error: ${errorData.message}`);
        return null;
      }
      
      if (attempt === maxRetries) {
        console.error(`❌ Request failed: ${error.message}`);
        return null;
      }
      
      await new Promise(resolve => setTimeout(resolve, Math.pow(2, attempt) * 1000));
    }
  }
  
  return null;
}

2. Log Errors for Debugging

Always log error details for debugging and monitoring:

Python Error Logging

import logging
import json

def log_api_error(error_response, request_data):
    logger = logging.getLogger('agenticpencil_api')
    
    error_info = {
        'timestamp': datetime.now().isoformat(),
        'error_code': error_response.get('code'),
        'error_message': error_response.get('message'),
        'request_endpoint': request_data.get('endpoint'),
        'request_params': request_data.get('params', {}),
        'incident_id': error_response.get('details', {}).get('incident_id')
    }
    
    logger.error(f"AgenticPencil API Error: {json.dumps(error_info)}")

3. User-Friendly Error Messages

Transform technical errors into user-friendly messages:

User-Friendly Error Mapping

ERROR_MESSAGES = {
    'INVALID_API_KEY': 'Your API key is invalid. Please check your configuration.',
    'RATE_LIMIT_EXCEEDED': 'You\'re sending requests too quickly. Please wait a moment and try again.',
    'INSUFFICIENT_CREDITS': 'You don\'ve used all your credits this month. Consider upgrading your plan.',
    'DOMAIN_NOT_FOUND': 'We couldn\'t analyze this domain. Please check the URL and try again.',
    'INTERNAL_SERVER_ERROR': 'Something went wrong on our end. Please try again in a few minutes.'
}

def get_user_friendly_error(error_code, default_message):
    return ERROR_MESSAGES.get(error_code, default_message)

Never expose raw error details to end users - always sanitize error messages to prevent information leakage.

Monitor error patterns - Frequent specific errors might indicate issues with your integration that need addressing.

Get Started

Resources

Error Response Format

HTTP Status Codes

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

429 Too Many Requests

500 Internal Server Error

Authentication Errors

Rate Limiting Errors

Request Validation Errors

Business Logic Errors

Plan and Billing Errors

Server Errors

Error Handling Best Practices

1. Implement Proper Error Handling

2. Log Errors for Debugging

3. User-Friendly Error Messages

​Error Response Format

​HTTP Status Codes

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

429 Too Many Requests

500 Internal Server Error

​Authentication Errors

​Rate Limiting Errors

​Request Validation Errors

​Business Logic Errors

​Plan and Billing Errors

​Server Errors

​Error Handling Best Practices

​1. Implement Proper Error Handling

​2. Log Errors for Debugging

​3. User-Friendly Error Messages

Error Response Format

HTTP Status Codes

Authentication Errors

Rate Limiting Errors

Request Validation Errors

Business Logic Errors

Plan and Billing Errors

Server Errors

Error Handling Best Practices

1. Implement Proper Error Handling

2. Log Errors for Debugging

3. User-Friendly Error Messages