Error Handling
=============

This section describes the error responses and status codes used by the Taglife API.

HTTP Status Codes
----------------

The API uses standard HTTP status codes to indicate the success or failure of requests:

**Success Codes:**
- `200 OK`: Request successful
- `201 Created`: Resource created successfully
- `204 No Content`: Request successful, no content returned

**Client Error Codes:**
- `400 Bad Request`: Invalid request syntax or parameters
- `401 Unauthorized`: Authentication required or failed
- `403 Forbidden`: Authenticated but not authorized
- `404 Not Found`: Resource not found
- `405 Method Not Allowed`: HTTP method not supported
- `409 Conflict`: Resource conflict (e.g., duplicate entry)
- `422 Unprocessable Entity`: Validation errors
- `429 Too Many Requests`: Rate limit exceeded

**Server Error Codes:**
- `500 Internal Server Error`: Unexpected server error
- `502 Bad Gateway`: Gateway error
- `503 Service Unavailable`: Service temporarily unavailable

Error Response Format
--------------------

All error responses follow a consistent format:

.. code-block:: json

   {
     "error": "error_code",
     "message": "Human-readable error message",
     "details": {
       "field": "Additional error details",
       "code": "SPECIFIC_ERROR_CODE"
     }
   }

Common Error Codes
-----------------

Authentication Errors
~~~~~~~~~~~~~~~~~~~~

**401 Unauthorized - Invalid Credentials:**

.. code-block:: json

   {
     "error": "invalid_credentials",
     "message": "Invalid username or password",
     "details": {
       "code": "AUTH_FAILED"
     }
   }

**401 Unauthorized - Token Expired:**

.. code-block:: json

   {
     "error": "token_expired",
     "message": "Authentication token has expired",
     "details": {
       "code": "TOKEN_EXPIRED",
       "expired_at": "2024-08-01T10:00:00Z"
     }
   }

**401 Unauthorized - Invalid Token:**

.. code-block:: json

   {
     "error": "invalid_token",
     "message": "Invalid or malformed authentication token",
     "details": {
       "code": "INVALID_TOKEN"
     }
   }

**403 Forbidden - Insufficient Permissions:**

.. code-block:: json

   {
     "error": "insufficient_permissions",
     "message": "You don't have permission to perform this action",
     "details": {
       "code": "PERMISSION_DENIED",
       "required_permissions": ["campaign:write"]
     }
   }

Validation Errors
~~~~~~~~~~~~~~~~

**400 Bad Request - Missing Required Fields:**

.. code-block:: json

   {
     "error": "validation_error",
     "message": "Required fields are missing",
     "details": {
       "code": "MISSING_FIELDS",
       "missing_fields": ["username", "email"]
     }
   }

**422 Unprocessable Entity - Invalid Field Values:**

.. code-block:: json

   {
     "error": "validation_error",
     "message": "Invalid field values",
     "details": {
       "code": "INVALID_VALUES",
       "field_errors": {
         "email": "Invalid email format",
         "age": "Age must be between 18 and 100"
       }
     }
   }

**422 Unprocessable Entity - File Upload Errors:**

.. code-block:: json

   {
     "error": "validation_error",
     "message": "File upload validation failed",
     "details": {
       "code": "FILE_VALIDATION_ERROR",
       "file_errors": {
         "screenshots": "File size exceeds maximum limit of 10MB"
       }
     }
   }

Resource Errors
~~~~~~~~~~~~~~

**404 Not Found - Resource Not Found:**

.. code-block:: json

   {
     "error": "not_found",
     "message": "Campaign not found",
     "details": {
       "code": "RESOURCE_NOT_FOUND",
       "resource_type": "campaign",
       "resource_id": "123"
     }
   }

**409 Conflict - Resource Already Exists:**

.. code-block:: json

   {
     "error": "conflict",
     "message": "User already exists with this email",
     "details": {
       "code": "DUPLICATE_RESOURCE",
       "resource_type": "user",
       "conflicting_field": "email"
     }
   }

**409 Conflict - Campaign Already Joined:**

.. code-block:: json

   {
     "error": "conflict",
     "message": "You have already joined this campaign",
     "details": {
       "code": "ALREADY_JOINED",
       "campaign_id": "123"
     }
   }

Business Logic Errors
~~~~~~~~~~~~~~~~~~~~

**400 Bad Request - Campaign Not Available:**

.. code-block:: json

   {
     "error": "business_error",
     "message": "Campaign is not available for joining",
     "details": {
       "code": "CAMPAIGN_NOT_AVAILABLE",
       "reason": "Campaign has reached maximum participants"
     }
   }

**400 Bad Request - Insufficient Balance:**

.. code-block:: json

   {
     "error": "business_error",
     "message": "Insufficient balance for payout",
     "details": {
       "code": "INSUFFICIENT_BALANCE",
       "required_amount": 50,
       "available_balance": 25
     }
   }

**400 Bad Request - Task Already Completed:**

.. code-block:: json

   {
     "error": "business_error",
     "message": "Task has already been completed",
     "details": {
       "code": "TASK_ALREADY_COMPLETED",
       "task_id": "456",
       "completed_at": "2024-08-01T10:00:00Z"
     }
   }

Rate Limiting Errors
~~~~~~~~~~~~~~~~~~~

**429 Too Many Requests - Rate Limit Exceeded:**

.. code-block:: json

   {
     "error": "rate_limit_exceeded",
     "message": "Too many requests, please try again later",
     "details": {
       "code": "RATE_LIMIT_EXCEEDED",
       "limit": 100,
       "reset_time": "2024-08-01T11:00:00Z"
     }
   }

Network Errors
~~~~~~~~~~~~~

**400 Bad Request - Network Connection Failed:**

.. code-block:: json

   {
     "error": "network_error",
     "message": "Failed to connect to social network",
     "details": {
       "code": "NETWORK_CONNECTION_FAILED",
       "network": "instagram",
       "reason": "Invalid access token"
     }
   }

**400 Bad Request - Network Not Supported:**

.. code-block:: json

   {
     "error": "network_error",
     "message": "Social network not supported",
     "details": {
       "code": "NETWORK_NOT_SUPPORTED",
       "network": "tiktok",
       "supported_networks": ["instagram", "facebook", "twitter"]
     }
   }

Payment Errors
~~~~~~~~~~~~~

**400 Bad Request - Payment Method Not Available:**

.. code-block:: json

   {
     "error": "payment_error",
     "message": "Payment method not available in your region",
     "details": {
       "code": "PAYMENT_METHOD_NOT_AVAILABLE",
       "method": "paypal",
       "available_methods": ["bank_transfer"]
     }
   }

**400 Bad Request - Bank Account Verification Failed:**

.. code-block:: json

   {
     "error": "payment_error",
     "message": "Bank account verification failed",
     "details": {
       "code": "BANK_VERIFICATION_FAILED",
       "reason": "Invalid routing number"
     }
   }

Server Errors
~~~~~~~~~~~~

**500 Internal Server Error:**

.. code-block:: json

   {
     "error": "internal_server_error",
     "message": "An unexpected error occurred",
     "details": {
       "code": "INTERNAL_ERROR",
       "request_id": "req_123456789"
     }
   }

**503 Service Unavailable:**

.. code-block:: json

   {
     "error": "service_unavailable",
     "message": "Service temporarily unavailable",
     "details": {
       "code": "SERVICE_UNAVAILABLE",
       "estimated_recovery": "2024-08-01T12:00:00Z"
     }
   }

Error Handling Best Practices
---------------------------

1. **Always Check Status Codes**: Don't rely solely on the response body to determine success/failure.

2. **Handle Rate Limiting**: Implement exponential backoff when receiving 429 errors.

3. **Validate Input**: Check for validation errors before making requests.

4. **Log Error Details**: Include error codes and request IDs in your logs for debugging.

5. **Implement Retry Logic**: For transient errors (5xx), implement retry logic with exponential backoff.

6. **User-Friendly Messages**: Display user-friendly error messages while logging technical details.

Example Error Handling
---------------------

**JavaScript:**

.. code-block:: javascript

   class TaglifeAPIError extends Error {
     constructor(message, status, code, details) {
       super(message);
       this.name = 'TaglifeAPIError';
       this.status = status;
       this.code = code;
       this.details = details;
     }
   }

   async function handleAPIRequest(requestFunction) {
     try {
       return await requestFunction();
     } catch (error) {
       if (error.response) {
         const { status, data } = error.response;
         
         // Handle rate limiting
         if (status === 429) {
           const resetTime = new Date(data.details.reset_time);
           const delay = resetTime.getTime() - Date.now();
           if (delay > 0) {
             await new Promise(resolve => setTimeout(resolve, delay));
             return handleAPIRequest(requestFunction);
           }
         }
         
         // Handle authentication errors
         if (status === 401) {
           // Redirect to login or refresh token
           throw new TaglifeAPIError('Authentication required', status, data.error, data.details);
         }
         
         // Handle validation errors
         if (status === 422) {
           const fieldErrors = data.details.field_errors || {};
           const errorMessage = Object.values(fieldErrors).join(', ');
           throw new TaglifeAPIError(errorMessage, status, data.error, data.details);
         }
         
         // Handle other errors
         throw new TaglifeAPIError(data.message || 'API Error', status, data.error, data.details);
       } else {
         throw new TaglifeAPIError('Network Error', 0, 'NETWORK_ERROR', null);
       }
     }
   }

**Python:**

.. code-block:: python

   import time
   from datetime import datetime
   import requests

   class TaglifeAPIError(Exception):
       def __init__(self, message, status_code, error_code, details):
           super().__init__(message)
           self.status_code = status_code
           self.error_code = error_code
           self.details = details

   def handle_api_request(api_instance, request_func, max_retries=3):
       """Handle API requests with proper error handling and retry logic"""
       for attempt in range(max_retries):
           try:
               return request_func()
           except requests.exceptions.RequestException as e:
               if hasattr(e, 'response') and e.response is not None:
                   status_code = e.response.status_code
                   try:
                       data = e.response.json()
                       error_code = data.get('error', 'UNKNOWN_ERROR')
                       details = data.get('details', {})
                   except ValueError:
                       error_code = 'INVALID_RESPONSE'
                       details = {}
                   
                   # Handle rate limiting
                   if status_code == 429:
                       reset_time_str = details.get('reset_time')
                       if reset_time_str:
                           reset_time = datetime.fromisoformat(reset_time_str.replace('Z', '+00:00'))
                           delay = (reset_time - datetime.now()).total_seconds()
                           if delay > 0:
                               time.sleep(delay)
                               continue
                   
                   # Handle authentication errors
                   if status_code == 401:
                       raise TaglifeAPIError('Authentication required', status_code, error_code, details)
                   
                   # Handle validation errors
                   if status_code == 422:
                       field_errors = details.get('field_errors', {})
                       error_message = ', '.join(field_errors.values())
                       raise TaglifeAPIError(error_message, status_code, error_code, details)
                   
                   # Handle server errors with retry
                   if status_code >= 500 and attempt < max_retries - 1:
                       time.sleep(2 ** attempt)  # Exponential backoff
                       continue
                   
                   # Handle other errors
                   error_message = data.get('message', 'API Error')
                   raise TaglifeAPIError(error_message, status_code, error_code, details)
               else:
                   if attempt < max_retries - 1:
                       time.sleep(2 ** attempt)  # Exponential backoff
                       continue
                   raise TaglifeAPIError('Network Error', 0, 'NETWORK_ERROR', None)

**cURL Error Handling:**

.. code-block:: bash

   # Function to handle API errors
   handle_api_error() {
     local status_code=$1
     local response_body=$2
     
     case $status_code in
       400)
         echo "Bad Request: $response_body"
         ;;
       401)
         echo "Unauthorized: Please check your credentials"
         ;;
       403)
         echo "Forbidden: You don't have permission for this action"
         ;;
       404)
         echo "Not Found: The requested resource was not found"
         ;;
       429)
         echo "Rate Limited: Too many requests, please wait"
         ;;
       500)
         echo "Server Error: Please try again later"
         ;;
       *)
         echo "Unknown Error ($status_code): $response_body"
         ;;
     esac
   }

   # Example usage
   response=$(curl -s -w "%{http_code}" -X GET https://api.taglife.com/api/get/campaigns/ \
     -H "Authorization: JWT $TOKEN" \
     -H "Content-Type: application/json")
   
   status_code="${response: -3}"
   response_body="${response%???}"
   
   if [ "$status_code" -eq 200 ]; then
     echo "Success: $response_body"
   else
     handle_api_error "$status_code" "$response_body"
   fi

Debugging Tips
-------------

1. **Check Request Headers**: Ensure all required headers are present and correctly formatted.

2. **Validate Request Body**: Verify that JSON payloads are properly formatted and contain required fields.

3. **Check Authentication**: Ensure tokens are valid and not expired.

4. **Review Rate Limits**: Check if you're hitting rate limits and implement appropriate delays.

5. **Examine Error Details**: Look at the `details` field in error responses for specific information.

6. **Use Request IDs**: Include request IDs in your logs for easier debugging with support.

7. **Test with cURL**: Use cURL to test API endpoints and verify expected behavior.

8. **Check API Status**: Verify that the API service is operational.

Common Troubleshooting
---------------------

**"Invalid token" errors:**
- Check if the token is properly formatted (should start with "JWT ")
- Verify the token hasn't expired
- Ensure you're using the correct token type

**"Validation error" responses:**
- Check all required fields are present
- Verify field formats (email, dates, etc.)
- Ensure file uploads meet size and format requirements

**"Rate limit exceeded" errors:**
- Implement exponential backoff
- Reduce request frequency
- Check the reset time in the error response

**"Network connection failed" errors:**
- Verify social network credentials
- Check if the social network service is available
- Ensure proper permissions are granted