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

# Errors and retry behavior

> Error payload shape, safe retry guidance, and how to pair retries with idempotency keys.

# Errors and retry behavior

Non-success responses use this envelope:

```json theme={null}
{
  "error": {
    "code": "SOME_CODE",
    "message": "Human-readable explanation",
    "issues": []
  }
}
```

## Retry guidance

* Retry transport failures.
* Retry idempotent writes with the same `Idempotency-Key`.
* Re-read durable state after async work instead of assuming the first response is complete.

## Practical rules

* Treat server-side failures as retry candidates only when the original write used a stable idempotency key.
* Treat fresh export download URLs as temporary and re-read them from `GET /exports/{exportId}` when needed.
* If a mutation is already in progress or conflicts with current state, inspect the returned `code` and retry only when the operation is still logically safe.

## Machine-readable clients

The shipped Node.js SDK and CLI normalize errors into structured objects with:

* `code`
* `message`
* `status`
* `retryable`

That makes it safe to branch automation logic without parsing free-form strings.