> ## Documentation Index
> Fetch the complete documentation index at: https://docs.galileo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# exception_handling

## Module

Decorators for resilient ingestion/telemetry operations.

These decorators should ONLY be used for fire-and-forget operations where failures
should not crash the user's application (e.g., trace ingestion, span logging).

DO NOT use for resource management operations (CRUD) - those should raise exceptions
so users get clear feedback about failures.

## async\_warn\_catch\_exception

```python theme={null}
def async_warn_catch_exception(logger: Logger=logging.getLogger(__name__),
                               exceptions: tuple[type[Exception], ...]=INFRASTRUCTURE_EXCEPTIONS) -> Callable
```

Decorator for resilient asynchronous ingestion/telemetry operations.

Catches infrastructure exceptions (network errors, timeouts) and logs them
as warnings instead of raising. Returns None when an exception is caught.

Use this decorator ONLY for fire-and-forget operations where failures
should not crash the user's application (e.g., async trace ingestion).

DO NOT use for resource management operations (CRUD) - those should raise.

**Arguments**

* `logger` (`Logger`): The logger to use for warning messages. Defaults to module logger.
* `exceptions` (`tuple[type[Exception], ...]`): Tuple of exception types to catch. Defaults to INFRASTRUCTURE\_EXCEPTIONS.

**Returns**

* `Callable`: A decorator that wraps the async function with exception handling.

**Examples**

```python theme={null}
@async_warn_catch_exception()
async def ingest_trace(trace_data: dict) -> None:
    # Network errors will be caught and logged, not raised
    await api_client.post("/traces", json=trace_data)
```

## retry\_on\_transient\_http\_error

```python theme={null}
def retry_on_transient_http_error(func: Callable) -> Callable
```

Decorator for backoff retry logic on transient HTTP errors.

This decorator is designed to work WITH the backoff library. It catches
GalileoHTTPException and decides whether to re-raise (triggering a retry)
or return None (giving up silently).

Retryable errors (re-raised for backoff):

* 404: Record not found (eventual consistency)
* 408: Request timeout
* 422: Parent record not found yet
* 429: Rate limited
* 500+: Server errors

Non-retryable errors (returns None, logs error):

* 401: Unauthorized
* 403: Forbidden
* 400: Bad request
* Other client errors

**Arguments**

* `func` (`Callable`): An async function to wrap with retry logic.

**Returns**

* `Callable`: The wrapped async function.

**Examples**

```python theme={null}
@backoff.on_exception(backoff.expo, Exception, max_tries=5)
@retry_on_transient_http_error
async def update_trace(request: TraceUpdateRequest) -> None:
    await api_client.update_trace(request)
```

**Notes**

This decorator only works with async functions. It's designed to be used
as the innermost decorator, with backoff as the outer decorator.

## warn\_catch\_exception

```python theme={null}
def warn_catch_exception(logger: Logger=logging.getLogger(__name__),
                         exceptions: tuple[type[Exception], ...]=INFRASTRUCTURE_EXCEPTIONS) -> Callable
```

Decorator for resilient synchronous ingestion/telemetry operations.

Catches infrastructure exceptions (network errors, timeouts) and logs them
as warnings instead of raising. Returns None when an exception is caught.

Use this decorator ONLY for fire-and-forget operations where failures
should not crash the user's application (e.g., trace ingestion).

DO NOT use for resource management operations (CRUD) - those should raise.

**Arguments**

* `logger` (`Logger`): The logger to use for warning messages. Defaults to module logger.
* `exceptions` (`tuple[type[Exception], ...]`): Tuple of exception types to catch. Defaults to INFRASTRUCTURE\_EXCEPTIONS.

**Returns**

* `Callable`: A decorator that wraps the function with exception handling.

**Examples**

```python theme={null}
@warn_catch_exception()
def ingest_trace(trace_data: dict) -> None:
    # Network errors will be caught and logged, not raised
    api_client.post("/traces", json=trace_data)
```