Skip to content

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!