一、EIOS 错误码体系：每个错误都是可编程的信号
良好的错误处理始于对错误类型和语义的精确理解。EIOS 的错误码体系采用 三级分类结构，每个错误码都是一个可编程的信号，而不是一段需要人工阅读的模糊文本。第一级是 HTTP 状态码，遵循 RFC 7231 标准：400 表示客户端请求格式有误（如缺少必填字段、参数类型错误），401 表示认证失败（API Key 无效或已过期），403 表示权限不足（API Key 无权访问该端点或资源），404 表示资源不存在，429 表示速率限制，500 表示服务端内部错误，503 表示服务暂时不可用。第二级是 EIOS 错误码（响应体中的 error.code 字段），采用 大写蛇形命名 格式，如 MODEL_OVERLOADED（模型当前负载过高）、TOKEN_LIMIT_EXCEEDED（单次请求超过了模型的最大上下文长度）、CONTENT_FILTERED（输出被安全策略拦截）。第三级是 错误子码（error.sub_code），提供更细粒度的原因，如 MODEL_OVERLOADED / QUEUE_FULL 表示请求队列已满，建议稍后重试；MODEL_OVERLOADED / REGION_DOWN 表示当前区域模型不可用，建议切换到备用区域。每个错误响应还包含 error.suggestion 字段——一条面向开发者的具体修复建议（例如："请将 max_tokens 从 32000 降低至 16000 以下，或使用支持更长上下文的模型版本"）。
二、可重试 vs 不可重试：错误分类的决策树
不是所有错误都适合重试。重试一个本不可重试的错误（如 API Key 无效）只会浪费资源并延迟问题的发现。EIOS 将错误分为三类，每一类有不同的处理策略。第一类：可立即重试的瞬时错误（Transient）——包括 429（速率限制）、503（服务暂时不可用）和 MODEL_OVERLOADED。这些错误的特点是通常会在短时间内自行恢复，适合指数退避重试。第二类：需要修改请求后重试的可恢复错误（Recoverable）——包括 400 中的参数超限类错误（如 TOKEN_LIMIT_EXCEEDED，可缩短输入后重试）、413（请求体过大，可压缩后重试）和 CONTENT_FILTERED（可修改输入措辞后重试）。第三类：不可重试的永久错误（Permanent）——包括 401（认证失败，需检查 API Key）、403（权限不足，需申请权限）、404（资源不存在，需检查 ID）和 400 中的格式错误（如 JSON 解析失败，需修复代码）。响应体中的 error.retryable 布尔字段（true/false）直接告知客户端是否应该重试，开发者无需自行维护错误分类逻辑。SDK 默认对 retryable: true 的错误自动重试，对 retryable: false 的错误立即抛出异常，由调用方处理。
三、重试策略：指数退避、抖动与幂等保障
盲目重试可能加剧问题——"惊群效应"下大量客户端同时重试将瞬时压垮刚恢复的服务。EIOS SDK 实施的 指数退避与随机抖动（Exponential Backoff with Jitter）策略有效避免了这一问题。退避公式为：wait = min(base * 2^attempt + random(0, jitter), max_wait)，其中 base 为初始等待时间（默认 1 秒），attempt 为当前重试次数（从 0 开始），jitter 为随机抖动范围（默认 0-50% 的等待时间），max_wait 为最大等待时间（默认 30 秒）。SDK 默认最多重试 3 次，总等待时间不超过 60 秒。对于需要 幂等性 的操作（如创建资源），请求中应携带 Idempotency-Key 请求头——一个客户端生成的唯一标识符。服务端在 24 小时内收到具有相同 Idempotency-Key 的重复请求时，直接返回首次执行的结果，而不会重复执行副作用操作。这对于创建 Agent、发布插件、创建 API Key 等操作尤为重要——网络超时后客户端不知道请求是否已成功，使用相同的 Idempotency-Key 安全重试，确保"最多创建一次"。SDK 在启用 idempotency: true 选项后自动为每个请求生成 UUID 格式的幂等键。
四、熔断器模式：当依赖不可靠时保护你自己
当 EIOS API 持续不可用时（如大规模区域性故障），不应让客户端无休止地重试，这既浪费客户端资源，也阻碍了服务端的恢复。此时应该引入 熔断器（Circuit Breaker） 模式。熔断器有三种状态：关闭（Closed）——正常工作状态，请求正常发送；打开（Open）——当错误率在时间窗口内超过阈值（如 60 秒内 50% 的请求失败）时，熔断器打开，新的请求不再发送至服务端，而是直接返回预设的降级响应或抛出快速失败异常。打开状态持续一段冷却时间后（如 30 秒），熔断器进入 半开（Half-Open） 状态——允许少量探测请求（如 3 个）通过以测试服务端是否恢复；如果探测请求成功，熔断器关闭恢复正常；如果失败，熔断器重新打开并重置冷却计时器。EIOS 的 Java 和 Go SDK 内置了基于 Resilience4j 和 go-resiliency 的熔断器实现，通过配置即可启用。Python SDK 可以通过集成 pybreaker 库实现。熔断器不仅保护了客户端（快速失败，不积累超时等待），也保护了服务端（减少无效请求，给予恢复时间）。更高级的用法是将熔断器状态暴露为 Metrics，在 Grafana 面板中可视化，让运维团队实时感知依赖健康状况。
五、超时控制：每个请求都应该有时限
一个没有设置超时的 HTTP 请求是生产环境中的定时炸弹。网络波动、服务端过载或死锁可能导致请求无限期挂起，占用连接池资源并阻塞调用线程，最终拖垮整个客户端应用。EIOS SDK 为每个端点设置了合理的 默认超时值：标准生成类端点（/v1/chat/completions）默认 120 秒，批量推理端点默认 300 秒，管理类端点（CRUD 操作）默认 30 秒，流式连接的空闲超时为 60 秒（即连续 60 秒未收到新事件则判定连接已死）。开发者可以通过 SDK 配置或单次请求参数覆盖默认值。超时控制应遵循 "总体死线"模式——为整个业务流程设置一个端到端的超时预算（如"从用户点击发送到 UI 展示回复，必须在 15 秒内完成"），然后将预算分配到流程的各个环节（网络传输 2 秒、服务端排队 3 秒、模型推理 8 秒、后处理 2 秒），任何环节超出预算即触发降级策略（如使用缓存结果、切换到更小的模型、或展示友好的超时提示）。
六、生产环境可靠性清单
以下是一份可以直接用于生产环境 Code Review 的 API 集成可靠性清单。第一部分，错误处理完备性：是否处理了所有可能的 HTTP 错误状态码（至少 4xx 和 5xx）？是否根据 error.retryable 字段决定重试策略？是否对不可重试的错误记录了详细的日志（含 traceId）？是否将面向用户的错误消息与面向开发者的错误细节分离？第二部分，重试策略正确性：是否使用了指数退避和随机抖动？是否设置了最大重试次数和总超时时间？对于非幂等操作是否携带了 Idempotency-Key？重试是否仅针对 retryable: true 的错误？第三部分，韧性模式：是否实现了熔断器？是否有降级路径（备选模型、缓存结果或无 AI 的基础规则）？是否有监控和告警（错误率、延迟分布、熔断器状态）？第四部分，资源管理：所有请求是否设置了超时？连接池是否配置了合理的上限和空闲回收？流式连接是否正确关闭（防止连接泄漏）？记住：优秀的错误处理不是"让所有请求成功"，而是"让每次失败都快速、可理解且容易恢复"。
