Error Handling

The Python SDK handles transient failures automatically and surfaces real errors clearly.

Retry behavior

The SDK retries requests that fail with transient HTTP statuses:

list[int]

default:"[429, 500, 502, 503]"

HTTP status codes that trigger an automatic retry.

int

default:"3"

Maximum number of retry attempts before raising.

float

default:"0.5 × 2^attempt seconds"

Exponential backoff between retries. First retry waits 0.5 s, second 1 s, third 2 s.

float

default:"30.0"

Request timeout in seconds. Configurable on the client.

Token refresh

On 401 Unauthorized, the SDK refreshes the access token once and retries the request. You do not manage tokens yourself.

Configuring timeout

from hexel import Hexel

client = Hexel(api_key="YOUR_API_KEY", timeout=60.0)

Handling errors

After exhausting retries, the SDK raises httpx.HTTPStatusError. Catch it to inspect the status and body:

import httpx
from hexel import Hexel

client = Hexel(api_key="YOUR_API_KEY")

try:
    instances = client.compute.instance.list(agent_id="YOUR_AGENT_ID")
except httpx.HTTPStatusError as e:
    print(f"Status {e.response.status_code}: {e.response.text}")
except httpx.TimeoutException:
    print("Request timed out")

Handling tool execution errors

import httpx
from hexel import Hexel

client = Hexel(api_key="YOUR_API_KEY")

try:
    result = client.tools.execute(
        tool_slug="GMAIL_SEND_EMAIL",
        input={"to": "user@example.com", "subject": "Test", "body": "Hello"},
    )
except httpx.HTTPStatusError as e:
    if e.response.status_code == 422:
        print("Invalid input:", e.response.text)
    else:
        print(f"Tool execution failed: {e.response.status_code}")

Common mistakes

Adding your own retry loop on top of the SDK. This compounds backoff; rely on the built-in retries.
Treating 429 as fatal. It is retried automatically; only persistent rate limiting surfaces as an error.

Best practices

Catch httpx.HTTPStatusError to inspect status and body.
Raise the timeout for known long-running operations rather than retrying.
Use idempotency keys for tool executions you may retry.

Resources

The client surface.

Tiers & Limits

Rate limits behind 429s.

Troubleshooting

Resolve common failures.

Examples

End-to-end examples.

Overview

Python SDK

CLI (hexel-tools)

Retry behavior

Token refresh

Configuring timeout

Handling errors

Handling tool execution errors

Common mistakes

Best practices

Resources

Tiers & Limits

Troubleshooting

Examples

​Retry behavior

​Token refresh

​Configuring timeout

​Handling errors

​Handling tool execution errors

​Common mistakes

​Best practices

​Related pages

Resources

Tiers & Limits

Troubleshooting

Examples

Retry behavior

Token refresh

Configuring timeout

Handling errors

Handling tool execution errors

Common mistakes

Best practices

Related pages