Error Handling

Read the envelope and handle each code appropriately:

import requests

response = requests.get(url, headers=headers)
if not response.ok:
    error = response.json()
    code = error["code"]
    if code == "unauthorized":
        # Handle authentication error
        print("Invalid or missing credential")
    elif code == "rate_limited":
        # Handle rate limiting
        print("Rate limited. Slow down and retry.")
    elif code == "invalid_request":
        # Handle validation errors
        for field_error in error["errors"]:
            print(f"{field_error['field']}: {field_error['message']}")
        if not error["errors"]:
            print(error["message"])
    elif code == "stale_cursor":
        # Restart pagination from the first page
        print("Cursor no longer valid. Restarting from the first page.")

For rate limiting and temporary errors, retry with exponential backoff:

import random
import time

import requests

# rate_limited, error, service_unavailable
RETRYABLE_STATUSES = {429, 500, 503}

def make_request_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)
        if response.ok:
            return response
        if response.status_code not in RETRYABLE_STATUSES:
            response.raise_for_status()
        # Exponential backoff with jitter
        wait_time = (2 ** attempt) + random.uniform(0, 1)
        time.sleep(wait_time)
    raise Exception("Max retries exceeded")

Log errors with enough context to trace them, and always keep the requestId:

import logging

import requests

logger = logging.getLogger(__name__)

response = requests.get(url, headers=headers)
if not response.ok:
    error = response.json()
    logger.error(
        "API request failed",
        extra={
            "status_code": response.status_code,
            "url": url,
            "code": error.get("code"),
            "request_id": error.get("requestId"),
            "message": error.get("message"),
        }
    )
    response.raise_for_status()

Transform error codes into messages your own users can act on:

def handle_api_error(error):
    code = error.get("code")
    if code == "unauthorized":
        return "Please check your API key and try again."
    elif code == "not_found":
        return "The requested resource was not found."
    elif code == "invalid_request":
        return "Please check your input data and try again."
    elif code == "rate_limited":
        return "Too many requests. Please wait a moment and try again."
    else:
        return "An unexpected error occurred. Please try again later."