> ## Documentation Index > Fetch the complete documentation index at: https://docs.li.fi/llms.txt > Use this file to discover all available pages before exploring further. # 认证、状态与重试契约 > 按操作处理 REST 与 MCP 的错误，避免将请求错误与交易结果混淆 ## 各入口的认证 * **Routing REST（`li.quest`）**：公开路由端点允许不带密钥访问，但受速率限制约束。认证请求使用 `x-lifi-api-key`。`GET /v1/keys/test` 等受保护端点要求有效密钥。 * **Earn REST（`earn.li.fi`）**：要求 `x-lifi-api-key`。不要将 routing 的访问规则或配额套用到 Earn。 * **通用 MCP，HTTP transport**：服务端接受 `Authorization: Bearer ` 或 `X-LiFi-Api-Key`；两者同时存在时，优先使用 Bearer key。选中的值通过 `x-lifi-api-key` 传给上游。这不授予签名或广播交易的权限。 * **通用 MCP，stdio transport**：服务端读取 `LIFI_API_KEY`。`test-api-key` 工具调用 routing 的 `/v1/keys/test`；routing key 测试成功不证明可以访问所有 LI.FI 产品。 * **SDK**：按已安装 SDK 版本的文档配置 API key，由客户端发送上游请求头。见 [SDK 配置](/sdk/configure-sdk)。 * **CLI 和 Intents**：使用各产品文档规定的认证方式，不要将通用 MCP 的 Bearer 适配或 routing key 当作通用凭证。 HTTP 请求头名称不区分大小写。不同大小写不构成契约不一致。不要记录或公开 key，应保存在服务端配置中。 ## 按操作理解结果 分别保留 HTTP status、API 数字 code、交易 `status` 和 `substatus`。以下是客户端处理建议，不是新的 REST 响应 schema，也不保证已部署 MCP 会返回这些结构化字段。 | 观察到的结果 | 含义 | 下一步 | | - | - | - | | HTTP 401/403 | 凭证或访问权限问题 | 检查 key 和 scope，不原样重试 | | HTTP 400/422 | 请求不合法 | 修正参数，不原样重试 | | status lookup：HTTP 404 / code 1003，或 `NOT_FOUND` | 结果未知 | 有界轮询，再核对源链；绝不自动重发 | | quote/route discovery：API code `1002`（`NoQuoteError`） | 当前请求没有可用路由 | 考虑修改参数；尚未授权任何交易 | | 其他 HTTP 404 | 接口或资源未找到 | 检查 endpoint 和响应内容，不直接判定无路由 | | `PENDING` | 仍在处理 | 有界轮询 | | `DONE` + `COMPLETED` | 已完成 | 核对目标链证据 | | `DONE` + `PARTIAL` | 已完成，但收到不同资产 | 核对实际资产；后续 swap 需要授权 | | `DONE` + `REFUNDED` | 退款结果 | 核对退回资金，不自动再次执行 | | `FAILED` | 接口报告执行失败 | 提出恢复方案前，核对源链和目标链证据 | | HTTP 429 | 被限流 | 延迟只读请求，限制重试次数 | | HTTP 5xx 或网络超时 | 请求结果不可用 | 有界重试安全读取；不推断交易执行失败 | ## 重试边界 重试 `GET /status` 或报价查询，不等于重试签名、approval、提交交易或存款。超时绝不授权新交易。考虑替换前必须保留原 hash 并核对其状态。修改 slippage 必须符合用户策略或获得明确授权。 如果返回 `Retry-After`，解析 delay-seconds 或 HTTP date，不要提前重试。否则采用带 jitter 的有界指数退避。`ratelimit-reset` 文档含义是距离重置的秒数，不是绝对 Unix timestamp。不同产品的 header 和配额可能不同。通用 MCP HTTP client 当前自行计算 backoff；不要假设它会向调用 Agent 暴露或严格执行 `Retry-After`。 ## MCP 部署边界 MCP transport 返回 HTTP 200 不代表业务成功，必须检查 `CallToolResult.isError` 和工具内容。当前通用 MCP 错误可能是文本，而不是 typed error object。Earn capability 响应和 structured outputs 取决于已部署版本；GitHub PR 不证明服务已部署。 参见 [Error Playbooks](/agents/reference/error-playbooks)、[Status & Recovery](/agents/workflows/status-recovery) 和 [Rate Limits](/api-reference/rate-limits)。 This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.