Error Handling

Understanding and handling errors in the Traceback Search API.

HTTP Status Codes

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

Status Code Meaning Description
200 OK Request successful
400 Bad Request Invalid request parameters
401 Unauthorized Invalid or missing API key
403 Forbidden API key lacks required permissions
404 Not Found Endpoint or resource not found
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Server-side error occurred
503 Service Unavailable API temporarily unavailable

Error Response Format

All error responses follow a consistent JSON format:

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "The 'phone_number' parameter is required",
    "details": {
      "parameter": "phone_number",
      "expected": "string in E.164 format"
    },
    "request_id": "req_1234567890abcdef"
  }
}

Common Error Codes

Authentication Errors

MISSING_API_KEY

Status: 401 Unauthorized

Cause: No API key provided in the request

Solution: Include your API key in the Authorization header

INVALID_API_KEY

Status: 401 Unauthorized

Cause: API key is invalid or expired

Solution: Verify your API key or generate a new one

Request Errors

INVALID_PARAMETER

Status: 400 Bad Request

Cause: Required parameter missing or invalid format

Solution: Check parameter requirements and format

INVALID_DATE_RANGE

Status: 400 Bad Request

Cause: Date range exceeds maximum allowed period

Solution: Reduce date range to 1 year or less

Rate Limiting Errors

RATE_LIMIT_EXCEEDED

Status: 429 Too Many Requests

Cause: Too many requests in a short time period

Solution: Implement exponential backoff and respect rate limits

Error Handling Best Practices

Retry Logic

Implement exponential backoff for transient errors (5xx status codes and 429):

import time
import random

def make_request_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries + 1):
        try:
            response = requests.get(url, headers=headers)
            
            if response.status_code == 200:
                return response.json()
            elif response.status_code == 429:
                # Rate limited - check Retry-After header
                retry_after = int(response.headers.get('Retry-After', 60))
                time.sleep(retry_after)
                continue
            elif response.status_code >= 500:
                # Server error - exponential backoff
                if attempt < max_retries:
                    delay = (2 ** attempt) + random.uniform(0, 1)
                    time.sleep(delay)
                    continue
            else:
                # Client error - don't retry
                response.raise_for_status()
                
        except requests.RequestException as e:
            if attempt < max_retries:
                delay = (2 ** attempt) + random.uniform(0, 1)
                time.sleep(delay)
                continue
            raise e
    
    raise Exception(f"Max retries ({max_retries}) exceeded")

Logging and Monitoring

Always log error details for debugging:

import logging

logger = logging.getLogger(__name__)

try:
    response = requests.get(url, headers=headers)
    response.raise_for_status()
except requests.HTTPError as e:
    error_data = e.response.json() if e.response.content else {}
    logger.error(
        f"API request failed: {e.response.status_code} - "
        f"Error: {error_data.get('error', {}).get('message', 'Unknown error')}"
        f"Request ID: {error_data.get('error', {}).get('request_id', 'N/A')}"
    )
    raise

Graceful Degradation

Design your application to handle API failures gracefully:

  • Cache successful responses when possible
  • Provide fallback behavior for non-critical features
  • Display user-friendly error messages
  • Queue requests for retry during outages
Important: Never expose raw API error messages to end users. Always provide user-friendly error messages while logging technical details for debugging.