> For the complete documentation index, see [llms.txt](https://docs.unitlab.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.unitlab.ai/api-sdk-cli/sdks/exceptions-timeouts-and-retries.md).

# Exceptions, timeouts, and retries

Handle authentication, validation, permission, subscription, not-found, network, request-timeout, and processing-timeout failures.

{% hint style="info" %}
**Outcome:** Handle authentication, validation, permission, subscription, not-found, network, request-timeout, and processing-timeout failures.
{% endhint %}

```python
from unitlab import (
    AuthenticationError, ValidationError, NotFoundError,
    PermissionDeniedError, SubscriptionError, NetworkError,
    RequestTimeoutError, ProcessingTimeoutError,
)

try:
    status = project.batch_queue("BATCH_ID").wait(timeout=900)
except ProcessingTimeoutError as exc:
    print("last status", exc.status)
except AuthenticationError:
    raise
except (ValidationError, PermissionDeniedError) as exc:
    print(exc.code, str(exc))
except RequestTimeoutError:
    # Inspect server-side state before retrying a mutation.
    raise
except NetworkError as exc:
    print(exc.code, str(exc))
```

`ValidationError` maps rejected input, `NotFoundError` missing resources, `PermissionDeniedError` forbidden actions, and `SubscriptionError` commercial entitlement failures. Three more classes cover specific cases:

* `ConflictError`: the API answers HTTP 409 because the resource is in a conflicting state. `exc.code` tells the cases apart, for example `release_in_progress` (a second release create while one is still being prepared) and `release_not_ready` (a download before the release is ready).
* `AnnotationImportError`: an annotation import commit has blocked records or file issues and `allow_partial` is `False`. Nothing is written; `exc.rows` and `exc.issues` list them.
* `AmbiguousUploadCompletionError`: every part of a file uploaded in parts was sent, but the request that confirms the upload failed, so the file may already be processing. Check the data list before uploading it again.

All inherit from `UnitlabError`. `ValidationError`, `NotFoundError`, `PermissionDeniedError`, `SubscriptionError`, `ConflictError`, and `AmbiguousUploadCompletionError` inherit from `NetworkError`, which is also raised itself for any other HTTP error answer and for a failed connection. `AuthenticationError`, `RequestTimeoutError`, and `AnnotationImportError` do not inherit from `NetworkError`, so `except NetworkError` does not catch them. `ProcessingTimeoutError` is a subclass of `RequestTimeoutError`: catch it first, as the sample does.

### Timeouts and retries

* Apart from file transfers (uploads and downloads), a request times out after 60 seconds by default and raises `RequestTimeoutError`. The release create and release download requests allow 600 seconds.
* Such a request is retried only when the connection cannot be established: up to 3 retries after the first attempt, waiting 0, 0.5, and 1 second. A request that timed out waiting for the answer, or that got an HTTP error answer, is not retried.
* `wait()` raises `ProcessingTimeoutError` when its `timeout` passes. The default is 1,800 seconds for a Batch Queue, 7,200 seconds for a release (also for `releases.create()`, which waits by default), and 25,200 seconds for an asset.
* While `wait()` polls, a status request that gets no answer (a timeout or a dropped connection) or a server error is asked again; the fourth such failure in a row is raised. Any other error answer is raised at once.
* `UnitlabClient` takes no timeout or retry setting. Pass `timeout=` to `wait()` to change its deadline.

### Operating contract

| Concern           | Required behavior                                                                |
| ----------------- | -------------------------------------------------------------------------------- |
| Execution surface | Pinned `unitlab==3.1.6` application environment on Python 3.10+.                 |
| Identity          | Least-privilege API key supplied through approved configuration.                 |
| Target resolution | Stable resource IDs and an explicitly bounded target set.                        |
| Success evidence  | Typed return fields, server-side state, and downstream acceptance of the result. |

### Failure and recovery boundary

| Condition                                       | Response                                                                                                     |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| Authentication or authorization fails           | Stop, correct the service identity or access model, rotate exposed credentials, and rerun a read-only check. |
| Validation or entitlement rejects the operation | Correct the input or entitlement; do not retry an unchanged request.                                         |
| A request times out                             | Inspect remote state before repeating a mutation because the server may have accepted it.                    |
| Asynchronous processing exceeds its deadline    | Preserve the Batch Queue or release ID, continue bounded monitoring, and inspect item-level failures.        |
| Only part of a batch succeeds                   | Keep successful identifiers, isolate failed rows, and retry only the corrected subset.                       |

{% hint style="warning" %}
Pin and test the production SDK version. Use stable IDs, keep secrets out of logs and command history, and record the correlation ID, target IDs, counts, final state, and redacted error details for material state changes.
{% endhint %}

***

> **Explore related Unitlab capabilities:** [enterprise data annotation workflows](https://unitlab.ai/en/data-annotation)
