Error Handling

The IPTO API uses standard HTTP status codes and provides detailed error messages to help you handle errors gracefully. This guide explains our error handling approach and best practices.

HTTP Status Codes

Status Code	Description
200	Success
201	Created
204	No Content
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
422	Validation Error
429	Too Many Requests
500	Internal Server Error

Error Response Format

All error responses follow this format:

{
  "detail": "Error message",
  "code": "ERROR_CODE",
  "field": "field_name",  // Optional
  "value": "invalid_value"  // Optional
}

Common Error Types

Authentication Errors

{
  "detail": "Invalid authentication credentials",
  "code": "AUTH_001"
}

{
  "detail": "Token has expired",
  "code": "AUTH_002"
}

Validation Errors

{
  "detail": "Invalid email format",
  "code": "VAL_001",
  "field": "email",
  "value": "invalid-email"
}

{
  "detail": "File size exceeds limit",
  "code": "VAL_002",
  "field": "file",
  "value": "2097152"
}

Resource Errors

{
  "detail": "Asset not found",
  "code": "RES_001",
  "field": "asset_id",
  "value": "non_existent_id"
}

{
  "detail": "Insufficient balance",
  "code": "RES_002",
  "field": "balance",
  "value": "0.1"
}

Error Codes

Authentication (AUTH_*)

Code	Description
AUTH_001	Invalid credentials
AUTH_002	Token expired
AUTH_003	Invalid token
AUTH_004	Missing token

Validation (VAL_*)

Code	Description
VAL_001	Invalid email
VAL_002	File too large
VAL_003	Invalid file type
VAL_004	Missing required field

Resource (RES_*)

Code	Description
RES_001	Not found
RES_002	Insufficient balance
RES_003	Already exists
RES_004	Permission denied

Rate Limit (RATE_*)

Code	Description
RATE_001	Too many requests
RATE_002	Rate limit exceeded
RATE_003	Quota exceeded

Handling Errors

Example: Error Handling in Python

import requests
from typing import Dict, Any

def handle_api_error(response: requests.Response) -> Dict[str, Any]:
    if response.status_code == 200:
        return response.json()
        
    error = response.json()
    
    if response.status_code == 401:
        # Handle authentication error
        refresh_token()
        return retry_request(response.request)
        
    if response.status_code == 422:
        # Handle validation error
        print(f"Validation error in field {error.get('field')}")
        return None
        
    if response.status_code == 429:
        # Handle rate limit
        retry_after = int(response.headers.get('Retry-After', 60))
        time.sleep(retry_after)
        return retry_request(response.request)
        
    # Handle other errors
    print(f"Error: {error.get('detail')}")
    return None

Example: Error Handling in JavaScript

async function handleApiError(response) {
  if (response.ok) {
    return await response.json();
  }
  
  const error = await response.json();
  
  switch (response.status) {
    case 401:
      // Handle authentication error
      await refreshToken();
      return retryRequest(response);
      
    case 422:
      // Handle validation error
      console.log(`Validation error in field ${error.field}`);
      return null;
      
    case 429:
      // Handle rate limit
      const retryAfter = response.headers.get('Retry-After') || 60;
      await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
      return retryRequest(response);
      
    default:
      // Handle other errors
      console.log(`Error: ${error.detail}`);
      return null;
  }
}

Best Practices

Always check response status codes
Implement proper error handling
Log errors for debugging
Use appropriate retry strategies
Handle rate limits gracefully
Validate input before sending
Use appropriate timeouts
Implement circuit breakers
Monitor error rates
Keep error messages user-friendly

Debugging Tips

Check the error code and message
Verify input parameters
Check authentication status
Monitor rate limits
Review API documentation
Check system status
Contact support if needed

Rate Limits FAQ