Base code
This commit is contained in:
Kunthawat Greethong
688
docs-site/docs/api/error-codes.md
Normal file
688
docs-site/docs/api/error-codes.md
Normal file
@@ -0,0 +1,688 @@
|
||||
# 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!*
|
||||
Reference in New Issue
Block a user