> ## 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.

# 错误与重试行为

> 错误负载结构、安全重试指南，以及如何将重试与幂等键配合使用。

# 错误与重试行为

非成功响应使用以下封装结构：

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

## 重试指南

* 重试传输层失败。
* 对幂等写入使用相同的 `Idempotency-Key` 进行重试。
* 异步工作完成后，重新读取持久化状态，而不是假设首次响应已经包含最终结果。

## 实用规则

* 仅当原始写入使用了稳定的幂等键时，才将服务端失败视为可重试的候选。
* 将新的导出下载 URL 视为临时的，需要时从 `GET /exports/{exportId}` 重新读取。
* 如果某个变更操作已在进行中或与当前状态冲突，请检查返回的 `code`，仅在该操作在逻辑上仍然安全时才重试。

## 机器可读客户端

随附的 Node.js SDK 和 CLI 会将错误规范化为结构化对象，包含：

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

这使得无需解析自由格式字符串，就能安全地对自动化逻辑进行分支处理。