> 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/apis/errors-pagination-and-retries.md).

# Errors, pagination, and retries

{% hint style="info" %}
**Outcome:** Implement deterministic errors, complete traversal, bounded polling, and state-aware retries.
{% endhint %}

### Error mapping

| Condition               | Caller behavior                                          |
| ----------------------- | -------------------------------------------------------- |
| 400 validation          | Correct the request; do not retry unchanged              |
| 401 authentication      | Stop and repair or rotate the key                        |
| 403 `permission_denied` | Review role and resource access                          |
| Other 403               | Review plan, quota, or entitlement                       |
| 404 or not found        | Verify workspace scope and stable ID                     |
| Timeout                 | Read remote state before repeating a mutation            |
| Other failure           | Preserve status and redacted error; retry only when safe |

### Pagination

Page-based lists return `results` and a complete `next` URL. Follow it until null without rebuilding the URL. Cloud browse returns `content` and a provider token; resend it as `next_token` with unchanged browse parameters.

### Poll a Batch Queue

```bash
curl --fail-with-body --silent --show-error \
  "$UNITLAB_API_URL/api/sdk/projects/PROJECT_ID/upload-sessions/QUEUE_ID/status/" \
  -H "Authorization: Api-Key $UNITLAB_API_KEY"
```

Processing is terminal when `processing` is zero, but failed items can remain. Inspect `failed` and then read the queue `/data/`.

### Retry decision

Use exponential backoff with jitter for transient reads. Before retrying create, attach, move, action, release, or delete operations, read the target to determine whether the first request succeeded.

Workflow actions and direct moves accept caller-generated idempotency keys. Reuse the same key only when resuming the same logical action.

### Request operating contract

| Concern           | Required behavior                                                                                     |
| ----------------- | ----------------------------------------------------------------------------------------------------- |
| Execution surface | TLS-verified client using the reviewed current public `/api/sdk/...` route contract.                  |
| Identity          | Least-privilege workspace service identity; secrets remain outside code and logs.                     |
| Request boundary  | URL-encoded stable IDs, explicit deadlines, structured errors, and complete pagination.               |
| Success evidence  | Response identifiers, read-after-write verification, and separate processing status for Batch Queues. |

{% hint style="warning" %}
Do not infer undocumented private routes. After a timeout, inspect remote state before repeating a mutation.
{% endhint %}