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:

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

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

401 Unauthorized - Token Expired:

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

401 Unauthorized - Invalid Token:

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

403 Forbidden - Insufficient Permissions:

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

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

422 Unprocessable Entity - Invalid Field Values:

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

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

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

409 Conflict - Resource Already Exists:

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

409 Conflict - Campaign Already Joined:

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

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

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

400 Bad Request - Task Already Completed:

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

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

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

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

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

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

Server Errors

500 Internal Server Error:

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

503 Service Unavailable:

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

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:

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:

# 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