689 lines
15 KiB
Markdown
689 lines
15 KiB
Markdown
# 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:
|
|
|
|
```json
|
|
{
|
|
"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.
|
|
|
|
```json
|
|
{
|
|
"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.
|
|
|
|
```json
|
|
{
|
|
"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.
|
|
|
|
```json
|
|
{
|
|
"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.
|
|
|
|
```json
|
|
{
|
|
"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.
|
|
|
|
```json
|
|
{
|
|
"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.
|
|
|
|
```json
|
|
{
|
|
"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.
|
|
|
|
```json
|
|
{
|
|
"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.
|
|
|
|
```json
|
|
{
|
|
"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.
|
|
|
|
```json
|
|
{
|
|
"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.
|
|
|
|
```json
|
|
{
|
|
"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.
|
|
|
|
```json
|
|
{
|
|
"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.
|
|
|
|
```json
|
|
{
|
|
"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.
|
|
|
|
```json
|
|
{
|
|
"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.
|
|
|
|
```json
|
|
{
|
|
"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.
|
|
|
|
```json
|
|
{
|
|
"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.
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```python
|
|
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
|
|
|
|
```python
|
|
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
|
|
|
|
```python
|
|
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](https://support.alwrity.com) or [Check our Status Page](https://status.alwrity.com) for service updates!*
|