Handling Errors

Error Format

{
  "error": {
    "message": "Human-readable description",
    "type": "error_type",
    "code": "specific_code"
  }
}

Retry Strategy

For transient errors (429, 503, 502), use exponential backoff:

import time
import requests

def retry_request(url, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(url, ...)
        if response.status_code == 200:
            return response
        if response.status_code in (429, 503, 502):
            wait = 2 ** attempt  # 1s, 2s, 4s
            time.sleep(wait)
            continue
        return response  # Non-retryable error
    return response

Non-Retryable Errors

Do not retry these errors:

Status	Type	Action
401	invalid_api_key	Fix API key
403	forbidden	Fix permissions
400	validation_error	Fix request
404	not_found	Check ID

Next Steps

• Errors — Complete error reference
• Rate Limits — Rate limiting details