Errors

All errors follow a consistent structure. Use HTTP status codes for broad categorization and the error body for specific handling.

Error Response Format

{
  "error": {
    "type": "invalid_request_error",
    "message": "Parameter 'externalUserId' is required"
  }
}

HTTP Status Codes

Error Types

The table below lists common error types to illustrate the response format. It is not exhaustive — each endpoint may return additional, operation-specific error types. Refer to the individual endpoint reference for the complete list of errors that endpoint can return.

Handling Strategies

Client Errors (4xx)

These indicate a problem with your request. Do not retry without fixing the issue.

if response.status_code == 400:
    error = response.json()["error"]
    log.warning(f"Bad request: {error['message']}")
    # Fix the request parameters
elif response.status_code == 409:
    error = response.json()["error"]
    if error["type"] == "profile_already_exists":
        # Handle duplicate: fetch existing profile instead
        pass

Server Errors (5xx)

These indicate a server-side issue. Retry with exponential backoff.

import time

max_retries = 3
for attempt in range(max_retries):
    response = make_request()
    if response.status_code < 500:
        break
    time.sleep(2 ** attempt)

Rate Limiting (429)

Respect the Retry-After header:

if response.status_code == 429:
    retry_after = int(response.headers.get("Retry-After", 60))
    time.sleep(retry_after)

Request ID

Every response includes an X-Request-Id header. Include this when contacting support for faster debugging:

X-Request-Id: req_abc123def456