igny8/backup-api-standard-v1/docs/ERROR-CODES.md

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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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

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

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

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

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

if response.status_code >= 500:
    # Retry with exponential backoff
    time.sleep(2 ** retry_count)
    # Retry request

---

Common Error Scenarios

Scenario 1: Missing Authentication

Request:

GET /api/v1/planner/keywords/
(No Authorization header)

Response (401):

{
  "success": false,
  "error": "Authentication required",
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Solution: Include Authorization: Bearer <token> header.

Scenario 2: Invalid Resource ID

Request:

GET /api/v1/planner/keywords/99999/
Authorization: Bearer <token>

Response (404):

{
  "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:

POST /api/v1/planner/keywords/
Authorization: Bearer <token>
Content-Type: application/json

{
  "seed_keyword_id": null,
  "site_id": 1
}

Response (400):

{
  "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/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