backup for restore later
This commit is contained in:
IGNY8 VPS (Salman)
407
backup-api-standard-v1/docs/ERROR-CODES.md
Normal file
407
backup-api-standard-v1/docs/ERROR-CODES.md
Normal file
@@ -0,0 +1,407 @@
|
||||
# API Error Codes Reference
|
||||
|
||||
**Version**: 1.0.0
|
||||
**Last Updated**: 2025-11-16
|
||||
|
||||
This document provides a comprehensive reference for all error codes and error scenarios in the IGNY8 API v1.0.
|
||||
|
||||
---
|
||||
|
||||
## Error Response Format
|
||||
|
||||
All errors follow this unified format:
|
||||
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"error": "Error message",
|
||||
"errors": {
|
||||
"field_name": ["Field-specific errors"]
|
||||
},
|
||||
"request_id": "550e8400-e29b-41d4-a716-446655440000"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## HTTP Status Codes
|
||||
|
||||
### 200 OK
|
||||
**Meaning**: Request successful
|
||||
**Response**: Success response with data
|
||||
|
||||
### 201 Created
|
||||
**Meaning**: Resource created successfully
|
||||
**Response**: Success response with created resource data
|
||||
|
||||
### 204 No Content
|
||||
**Meaning**: Resource deleted successfully
|
||||
**Response**: Empty response body
|
||||
|
||||
### 400 Bad Request
|
||||
**Meaning**: Validation error or invalid request
|
||||
**Common Causes**:
|
||||
- Missing required fields
|
||||
- Invalid field values
|
||||
- Invalid data format
|
||||
- Business logic validation failures
|
||||
|
||||
**Example**:
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"error": "Validation failed",
|
||||
"errors": {
|
||||
"email": ["This field is required"],
|
||||
"password": ["Password must be at least 8 characters"]
|
||||
},
|
||||
"request_id": "550e8400-e29b-41d4-a716-446655440000"
|
||||
}
|
||||
```
|
||||
|
||||
### 401 Unauthorized
|
||||
**Meaning**: Authentication required
|
||||
**Common Causes**:
|
||||
- Missing Authorization header
|
||||
- Invalid or expired token
|
||||
- Token not provided
|
||||
|
||||
**Example**:
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"error": "Authentication required",
|
||||
"request_id": "550e8400-e29b-41d4-a716-446655440000"
|
||||
}
|
||||
```
|
||||
|
||||
### 403 Forbidden
|
||||
**Meaning**: Permission denied
|
||||
**Common Causes**:
|
||||
- User lacks required role
|
||||
- User doesn't have access to resource
|
||||
- Account/site/sector access denied
|
||||
|
||||
**Example**:
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"error": "Permission denied",
|
||||
"request_id": "550e8400-e29b-41d4-a716-446655440000"
|
||||
}
|
||||
```
|
||||
|
||||
### 404 Not Found
|
||||
**Meaning**: Resource not found
|
||||
**Common Causes**:
|
||||
- Invalid resource ID
|
||||
- Resource doesn't exist
|
||||
- Resource belongs to different account
|
||||
|
||||
**Example**:
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"error": "Resource not found",
|
||||
"request_id": "550e8400-e29b-41d4-a716-446655440000"
|
||||
}
|
||||
```
|
||||
|
||||
### 409 Conflict
|
||||
**Meaning**: Resource conflict
|
||||
**Common Causes**:
|
||||
- Duplicate resource (e.g., email already exists)
|
||||
- Resource state conflict
|
||||
- Concurrent modification
|
||||
|
||||
**Example**:
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"error": "Conflict",
|
||||
"errors": {
|
||||
"email": ["User with this email already exists"]
|
||||
},
|
||||
"request_id": "550e8400-e29b-41d4-a716-446655440000"
|
||||
}
|
||||
```
|
||||
|
||||
### 422 Unprocessable Entity
|
||||
**Meaning**: Validation failed
|
||||
**Common Causes**:
|
||||
- Complex validation rules failed
|
||||
- Business logic validation failed
|
||||
- Data integrity constraints violated
|
||||
|
||||
**Example**:
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"error": "Validation failed",
|
||||
"errors": {
|
||||
"site": ["Site must belong to your account"],
|
||||
"sector": ["Sector must belong to the selected site"]
|
||||
},
|
||||
"request_id": "550e8400-e29b-41d4-a716-446655440000"
|
||||
}
|
||||
```
|
||||
|
||||
### 429 Too Many Requests
|
||||
**Meaning**: Rate limit exceeded
|
||||
**Common Causes**:
|
||||
- Too many requests in time window
|
||||
- AI function rate limit exceeded
|
||||
- Authentication rate limit exceeded
|
||||
|
||||
**Response Headers**:
|
||||
- `X-Throttle-Limit`: Maximum requests allowed
|
||||
- `X-Throttle-Remaining`: Remaining requests (0)
|
||||
- `X-Throttle-Reset`: Unix timestamp when limit resets
|
||||
|
||||
**Example**:
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"error": "Rate limit exceeded",
|
||||
"request_id": "550e8400-e29b-41d4-a716-446655440000"
|
||||
}
|
||||
```
|
||||
|
||||
**Solution**: Wait until `X-Throttle-Reset` timestamp before retrying.
|
||||
|
||||
### 500 Internal Server Error
|
||||
**Meaning**: Server error
|
||||
**Common Causes**:
|
||||
- Unexpected server error
|
||||
- Database error
|
||||
- External service failure
|
||||
|
||||
**Example**:
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"error": "Internal server error",
|
||||
"request_id": "550e8400-e29b-41d4-a716-446655440000"
|
||||
}
|
||||
```
|
||||
|
||||
**Solution**: Retry request. If persistent, contact support with `request_id`.
|
||||
|
||||
---
|
||||
|
||||
## Field-Specific Error Messages
|
||||
|
||||
### Authentication Errors
|
||||
|
||||
| Field | Error Message | Description |
|
||||
|-------|---------------|-------------|
|
||||
| `email` | "This field is required" | Email not provided |
|
||||
| `email` | "Invalid email format" | Email format invalid |
|
||||
| `email` | "User with this email already exists" | Email already registered |
|
||||
| `password` | "This field is required" | Password not provided |
|
||||
| `password` | "Password must be at least 8 characters" | Password too short |
|
||||
| `password` | "Invalid credentials" | Wrong password |
|
||||
|
||||
### Planner Module Errors
|
||||
|
||||
| Field | Error Message | Description |
|
||||
|-------|---------------|-------------|
|
||||
| `seed_keyword_id` | "This field is required" | Seed keyword not provided |
|
||||
| `seed_keyword_id` | "Invalid seed keyword" | Seed keyword doesn't exist |
|
||||
| `site_id` | "This field is required" | Site not provided |
|
||||
| `site_id` | "Site must belong to your account" | Site access denied |
|
||||
| `sector_id` | "This field is required" | Sector not provided |
|
||||
| `sector_id` | "Sector must belong to the selected site" | Sector-site mismatch |
|
||||
| `status` | "Invalid status value" | Status value not allowed |
|
||||
|
||||
### Writer Module Errors
|
||||
|
||||
| Field | Error Message | Description |
|
||||
|-------|---------------|-------------|
|
||||
| `title` | "This field is required" | Title not provided |
|
||||
| `site_id` | "This field is required" | Site not provided |
|
||||
| `sector_id` | "This field is required" | Sector not provided |
|
||||
| `image_type` | "Invalid image type" | Image type not allowed |
|
||||
|
||||
### System Module Errors
|
||||
|
||||
| Field | Error Message | Description |
|
||||
|-------|---------------|-------------|
|
||||
| `api_key` | "This field is required" | API key not provided |
|
||||
| `api_key` | "Invalid API key format" | API key format invalid |
|
||||
| `integration_type` | "Invalid integration type" | Integration type not allowed |
|
||||
|
||||
### Billing Module Errors
|
||||
|
||||
| Field | Error Message | Description |
|
||||
|-------|---------------|-------------|
|
||||
| `amount` | "This field is required" | Amount not provided |
|
||||
| `amount` | "Amount must be positive" | Invalid amount value |
|
||||
| `credits` | "Insufficient credits" | Not enough credits available |
|
||||
|
||||
---
|
||||
|
||||
## Error Handling Best Practices
|
||||
|
||||
### 1. Always Check `success` Field
|
||||
|
||||
```python
|
||||
response = requests.get(url, headers=headers)
|
||||
data = response.json()
|
||||
|
||||
if data['success']:
|
||||
# Handle success
|
||||
result = data['data'] or data['results']
|
||||
else:
|
||||
# Handle error
|
||||
error_message = data['error']
|
||||
field_errors = data.get('errors', {})
|
||||
```
|
||||
|
||||
### 2. Handle Field-Specific Errors
|
||||
|
||||
```python
|
||||
if not data['success']:
|
||||
if 'errors' in data:
|
||||
for field, errors in data['errors'].items():
|
||||
print(f"{field}: {', '.join(errors)}")
|
||||
else:
|
||||
print(f"Error: {data['error']}")
|
||||
```
|
||||
|
||||
### 3. Use Request ID for Support
|
||||
|
||||
```python
|
||||
if not data['success']:
|
||||
request_id = data.get('request_id')
|
||||
print(f"Error occurred. Request ID: {request_id}")
|
||||
# Include request_id when contacting support
|
||||
```
|
||||
|
||||
### 4. Handle Rate Limiting
|
||||
|
||||
```python
|
||||
if response.status_code == 429:
|
||||
reset_time = response.headers.get('X-Throttle-Reset')
|
||||
wait_seconds = int(reset_time) - int(time.time())
|
||||
print(f"Rate limited. Wait {wait_seconds} seconds.")
|
||||
time.sleep(wait_seconds)
|
||||
# Retry request
|
||||
```
|
||||
|
||||
### 5. Retry on Server Errors
|
||||
|
||||
```python
|
||||
if response.status_code >= 500:
|
||||
# Retry with exponential backoff
|
||||
time.sleep(2 ** retry_count)
|
||||
# Retry request
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Error Scenarios
|
||||
|
||||
### Scenario 1: Missing Authentication
|
||||
|
||||
**Request**:
|
||||
```http
|
||||
GET /api/v1/planner/keywords/
|
||||
(No Authorization header)
|
||||
```
|
||||
|
||||
**Response** (401):
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"error": "Authentication required",
|
||||
"request_id": "550e8400-e29b-41d4-a716-446655440000"
|
||||
}
|
||||
```
|
||||
|
||||
**Solution**: Include `Authorization: Bearer <token>` header.
|
||||
|
||||
### Scenario 2: Invalid Resource ID
|
||||
|
||||
**Request**:
|
||||
```http
|
||||
GET /api/v1/planner/keywords/99999/
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**Response** (404):
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"error": "Resource not found",
|
||||
"request_id": "550e8400-e29b-41d4-a716-446655440000"
|
||||
}
|
||||
```
|
||||
|
||||
**Solution**: Verify resource ID exists and belongs to your account.
|
||||
|
||||
### Scenario 3: Validation Error
|
||||
|
||||
**Request**:
|
||||
```http
|
||||
POST /api/v1/planner/keywords/
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"seed_keyword_id": null,
|
||||
"site_id": 1
|
||||
}
|
||||
```
|
||||
|
||||
**Response** (400):
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"error": "Validation failed",
|
||||
"errors": {
|
||||
"seed_keyword_id": ["This field is required"],
|
||||
"sector_id": ["This field is required"]
|
||||
},
|
||||
"request_id": "550e8400-e29b-41d4-a716-446655440000"
|
||||
}
|
||||
```
|
||||
|
||||
**Solution**: Provide all required fields with valid values.
|
||||
|
||||
### Scenario 4: Rate Limit Exceeded
|
||||
|
||||
**Request**: Multiple rapid requests
|
||||
|
||||
**Response** (429):
|
||||
```http
|
||||
HTTP/1.1 429 Too Many Requests
|
||||
X-Throttle-Limit: 60
|
||||
X-Throttle-Remaining: 0
|
||||
X-Throttle-Reset: 1700123456
|
||||
|
||||
{
|
||||
"success": false,
|
||||
"error": "Rate limit exceeded",
|
||||
"request_id": "550e8400-e29b-41d4-a716-446655440000"
|
||||
}
|
||||
```
|
||||
|
||||
**Solution**: Wait until `X-Throttle-Reset` timestamp, then retry.
|
||||
|
||||
---
|
||||
|
||||
## Debugging Tips
|
||||
|
||||
1. **Always include `request_id`** when reporting errors
|
||||
2. **Check response headers** for rate limit information
|
||||
3. **Verify authentication token** is valid and not expired
|
||||
4. **Check field-specific errors** in `errors` object
|
||||
5. **Review request payload** matches API specification
|
||||
6. **Use Swagger UI** to test endpoints interactively
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-11-16
|
||||
**API Version**: 1.0.0
|
||||
|
||||
Reference in New Issue
Block a user