moreminimore-marketing/docs-site/docs/api/error-codes.md

API Error Codes

This comprehensive reference covers all error codes returned by the ALwrity API, including descriptions, possible causes, and recommended solutions.

Error Response Format

All API errors follow a consistent format:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {
      "field": "Additional error details",
      "suggestion": "Recommended action"
    }
  },
  "timestamp": "2024-01-15T10:30:00Z",
  "request_id": "req_123456789"
}

HTTP Status Codes

4xx Client Errors

Status	Description
400	Bad Request - Invalid request format
401	Unauthorized - Authentication required
403	Forbidden - Insufficient permissions
404	Not Found - Resource not found
409	Conflict - Resource conflict
422	Unprocessable Entity - Validation error
429	Too Many Requests - Rate limit exceeded

5xx Server Errors

Status	Description
500	Internal Server Error - Server error
502	Bad Gateway - Upstream service error
503	Service Unavailable - Service temporarily down
504	Gateway Timeout - Request timeout

Authentication Errors

INVALID_API_KEY

Status: 401 Unauthorized

Description: The provided API key is invalid, expired, or malformed.

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or expired",
    "details": {
      "key_id": "key_123456789",
      "suggestion": "Please check your API key or generate a new one"
    }
  }
}

Causes:

• API key is incorrect
• API key has expired
• API key format is invalid

Solutions:

• Verify API key is correct
• Generate a new API key
• Check API key format

MISSING_API_KEY

Status: 401 Unauthorized

Description: No API key provided in the request.

{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key is required for authentication",
    "details": {
      "header": "Authorization: Bearer YOUR_API_KEY",
      "suggestion": "Include your API key in the Authorization header"
    }
  }
}

Causes:

• Missing Authorization header
• Incorrect header format

Solutions:

• Add Authorization header
• Use correct Bearer token format

INSUFFICIENT_PERMISSIONS

Status: 403 Forbidden

Description: API key doesn't have required permissions.

{
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "API key does not have required permissions",
    "details": {
      "required": ["write"],
      "granted": ["read"],
      "suggestion": "Upgrade your API key permissions or use a different key"
    }
  }
}

Causes:

• API key has read-only permissions
• Trying to perform write operation
• Key doesn't have specific feature access

Solutions:

• Use API key with write permissions
• Request permission upgrade
• Use appropriate key for operation

Rate Limiting Errors

RATE_LIMIT_EXCEEDED

Status: 429 Too Many Requests

Description: Request rate limit exceeded.

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please try again later.",
    "details": {
      "limit": 60,
      "remaining": 0,
      "reset_time": "2024-01-15T10:31:00Z",
      "retry_after": 60,
      "suggestion": "Wait 60 seconds before retrying or upgrade your plan"
    }
  }
}

Causes:

• Too many requests in time window
• Exceeded daily quota
• High resource usage

Solutions:

• Wait for rate limit reset
• Implement exponential backoff
• Upgrade to higher plan
• Optimize request frequency

QUOTA_EXCEEDED

Status: 429 Too Many Requests

Description: Daily or monthly quota exceeded.

{
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Daily quota exceeded",
    "details": {
      "quota_type": "daily",
      "limit": 1000,
      "used": 1000,
      "reset_time": "2024-01-16T00:00:00Z",
      "suggestion": "Wait until quota resets or upgrade your plan"
    }
  }
}

Causes:

• Daily request limit reached
• Monthly quota exceeded
• Feature-specific quota exceeded

Solutions:

• Wait for quota reset
• Upgrade plan for higher limits
• Optimize API usage
• Use caching to reduce requests

Validation Errors

VALIDATION_ERROR

Status: 422 Unprocessable Entity

Description: Request validation failed.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": {
      "field": "topic",
      "message": "Topic is required and must be at least 3 characters",
      "suggestion": "Provide a valid topic with at least 3 characters"
    }
  }
}

Causes:

• Missing required fields
• Invalid field values
• Field format errors
• Value constraints violated

Solutions:

• Check required fields
• Validate field formats
• Ensure values meet constraints
• Review API documentation

INVALID_REQUEST_FORMAT

Status: 400 Bad Request

Description: Request format is invalid.

{
  "error": {
    "code": "INVALID_REQUEST_FORMAT",
    "message": "Request body must be valid JSON",
    "details": {
      "content_type": "application/json",
      "suggestion": "Ensure request body is valid JSON with correct Content-Type header"
    }
  }
}

Causes:

• Invalid JSON format
• Missing Content-Type header
• Incorrect content type
• Malformed request body

Solutions:

• Validate JSON format
• Set correct Content-Type header
• Check request body structure
• Use proper encoding

Content Generation Errors

CONTENT_GENERATION_FAILED

Status: 500 Internal Server Error

Description: Content generation process failed.

{
  "error": {
    "code": "CONTENT_GENERATION_FAILED",
    "message": "Failed to generate content",
    "details": {
      "reason": "AI service timeout",
      "suggestion": "Try again with a shorter content length or contact support"
    }
  }
}

Causes:

• AI service timeout
• Content too long
• Invalid parameters
• Service overload

Solutions:

• Reduce content length
• Retry request
• Check parameters
• Contact support

CONTENT_TOO_LONG

Status: 422 Unprocessable Entity

Description: Content exceeds maximum length limit.

{
  "error": {
    "code": "CONTENT_TOO_LONG",
    "message": "Content exceeds maximum length limit",
    "details": {
      "max_length": 10000,
      "provided_length": 15000,
      "suggestion": "Reduce content length to 10,000 characters or less"
    }
  }
}

Causes:

• Content exceeds character limit
• Word count too high
• Input text too long

Solutions:

• Reduce content length
• Split into multiple requests
• Use appropriate limits
• Check content size

INVALID_CONTENT_TYPE

Status: 422 Unprocessable Entity

Description: Invalid content type specified.

{
  "error": {
    "code": "INVALID_CONTENT_TYPE",
    "message": "Invalid content type specified",
    "details": {
      "provided": "invalid_type",
      "valid_types": ["blog_post", "social_media", "email", "article"],
      "suggestion": "Use one of the valid content types"
    }
  }
}

Causes:

• Unsupported content type
• Typo in content type
• Missing content type

Solutions:

• Use valid content type
• Check spelling
• Review documentation
• Use default type

Research and SEO Errors

RESEARCH_FAILED

Status: 500 Internal Server Error

Description: Research process failed.

{
  "error": {
    "code": "RESEARCH_FAILED",
    "message": "Failed to perform research",
    "details": {
      "reason": "External service unavailable",
      "suggestion": "Try again later or use cached research data"
    }
  }
}

Causes:

• External service down
• Network connectivity issues
• Research service timeout
• Invalid research parameters

Solutions:

• Retry request
• Check network connection
• Use cached data
• Contact support

SEO_ANALYSIS_FAILED

Status: 500 Internal Server Error

Description: SEO analysis failed.

{
  "error": {
    "code": "SEO_ANALYSIS_FAILED",
    "message": "Failed to perform SEO analysis",
    "details": {
      "reason": "Content parsing error",
      "suggestion": "Ensure content is properly formatted and try again"
    }
  }
}

Causes:

• Content parsing issues
• Invalid HTML format
• Missing content elements
• Analysis service error

Solutions:

• Check content format
• Ensure valid HTML
• Retry analysis
• Contact support

Resource Errors

RESOURCE_NOT_FOUND

Status: 404 Not Found

Description: Requested resource not found.

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Requested resource not found",
    "details": {
      "resource_type": "content",
      "resource_id": "content_123456789",
      "suggestion": "Check resource ID or create new resource"
    }
  }
}

Causes:

• Invalid resource ID
• Resource deleted
• Resource not accessible
• Wrong resource type

Solutions:

• Verify resource ID
• Check resource exists
• Ensure proper permissions
• Use correct resource type

RESOURCE_CONFLICT

Status: 409 Conflict

Description: Resource conflict detected.

{
  "error": {
    "code": "RESOURCE_CONFLICT",
    "message": "Resource conflict detected",
    "details": {
      "conflict_type": "duplicate_name",
      "existing_resource": "content_123456789",
      "suggestion": "Use a different name or update existing resource"
    }
  }
}

Causes:

• Duplicate resource name
• Concurrent modification
• Resource already exists
• Version conflict

Solutions:

• Use unique name
• Check for existing resources
• Handle concurrency
• Resolve version conflicts

Service Errors

SERVICE_UNAVAILABLE

Status: 503 Service Unavailable

Description: Service temporarily unavailable.

{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Service temporarily unavailable",
    "details": {
      "reason": "Maintenance in progress",
      "estimated_recovery": "2024-01-15T12:00:00Z",
      "suggestion": "Try again after the estimated recovery time"
    }
  }
}

Causes:

• Scheduled maintenance
• Service overload
• Infrastructure issues
• Planned downtime

Solutions:

• Wait for service recovery
• Check status page
• Retry after delay
• Contact support

INTERNAL_SERVER_ERROR

Status: 500 Internal Server Error

Description: Internal server error occurred.

{
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "message": "An internal server error occurred",
    "details": {
      "request_id": "req_123456789",
      "suggestion": "Retry the request or contact support if the issue persists"
    }
  }
}

Causes:

• Unexpected server error
• Database issues
• Third-party service failure
• Configuration problems

Solutions:

• Retry request
• Check status page
• Contact support
• Provide request ID

Error Handling Best Practices

Client-Side Handling

import requests
import time

def handle_api_error(response):
    """Handle API errors with appropriate actions."""
    
    if response.status_code == 401:
        # Authentication error
        print("Authentication failed. Check your API key.")
        return None
    
    elif response.status_code == 429:
        # Rate limit error
        retry_after = response.headers.get('Retry-After', 60)
        print(f"Rate limited. Retrying in {retry_after} seconds...")
        time.sleep(int(retry_after))
        return "retry"
    
    elif response.status_code == 422:
        # Validation error
        error_data = response.json()
        print(f"Validation error: {error_data['error']['message']}")
        return None
    
    elif response.status_code >= 500:
        # Server error
        print("Server error. Please try again later.")
        return "retry"
    
    else:
        # Other errors
        print(f"Unexpected error: {response.status_code}")
        return None

Retry Logic

def make_request_with_retry(url, headers, data, max_retries=3):
    """Make API request with retry logic."""
    
    for attempt in range(max_retries):
        try:
            response = requests.post(url, headers=headers, json=data)
            
            if response.status_code == 200:
                return response.json()
            
            # Handle specific errors
            result = handle_api_error(response)
            
            if result == "retry" and attempt < max_retries - 1:
                continue
            elif result is None:
                return None
            else:
                return response.json()
                
        except requests.exceptions.RequestException as e:
            print(f"Request failed: {e}")
            if attempt < max_retries - 1:
                time.sleep(2 ** attempt)  # Exponential backoff
                continue
            else:
                raise
    
    return None

Logging and Monitoring

import logging

def log_api_error(error_data, request_id=None):
    """Log API errors for monitoring and debugging."""
    
    logger = logging.getLogger('alwrity_api')
    
    error_info = {
        'error_code': error_data.get('code'),
        'error_message': error_data.get('message'),
        'request_id': request_id,
        'timestamp': error_data.get('timestamp')
    }
    
    logger.error(f"API Error: {error_info}")
    
    # Send to monitoring service
    send_to_monitoring(error_info)

Troubleshooting Guide

Common Issues

Authentication Problems

1. Check API key format: Ensure proper Bearer token format
2. Verify key validity: Check if key is active and not expired
3. Check permissions: Ensure key has required permissions
4. Test with simple request: Use health check endpoint

Rate Limiting Issues

1. Monitor usage: Track your API usage patterns
2. Implement backoff: Use exponential backoff for retries
3. Optimize requests: Reduce unnecessary API calls
4. Consider upgrading: Evaluate if you need higher limits

Validation Errors

1. Check required fields: Ensure all required fields are provided
2. Validate formats: Check field formats and constraints
3. Review documentation: Verify parameter requirements
4. Test with minimal data: Start with simple requests

Getting Help

• API Documentation: Check endpoint-specific documentation
• Status Page: Monitor service status and incidents
• Support: Contact support for persistent issues
• Community: Join developer community for help
• GitHub Issues: Report bugs and request features

---

Need help with API errors? Contact Support or Check our Status Page for service updates!