错误码

#错误的结构

详情由 detail 键给出。对于校验错误，它会指出出错的值，并在存在有限取值列表时一并列出。

{
  "detail": "Symbole 'PEPEUSDT' inconnu. Valeurs acceptees : BTCUSDT, ETHUSDT, ..."
}

与方案相关的拒绝有固定结构，由网关设置：status、timestamp 和 detail，基于时间的拒绝还会加上 retry_after（同样出现在 Retry-After 响应头中）。X-Deny-Reason 响应头指明原因：rate、quota、family、websocket 或 key。

{
  "status": "error",
  "timestamp": 1775648290510,
  "detail": "Debit depasse : votre offre autorise un nombre limite de requetes par minute.",
  "retry_after": 1
}

深度相关的 403 由接口本身返回，不带 X-Deny-Reason：其 detail 总是以 « Profondeur d’historique hors offre » 开头，并给出该周期下可使用的最大 limit。各方案的窗口见使用限制页面。

#HTTP 状态码

#指标

校验按固定顺序进行（周期、结果数量、交易对、指标解析、上限规则、读取 K 线），以第一个失败为准。因此修正后的正文可能会暴露第二个错误。

#WebSocket 数据流

每个无法满足的请求都会收到 op: error 消息，说明期望的内容：有效交易对列表、频道列表、depth 的范围。有三种情况不会产生错误，而是关闭连接：

密钥在握手时校验，早于连接建立：密钥缺失或无效，或方案不含数据流（Free），会在握手时收到 403，X-Deny-Reason 为 key 或 websocket。此时出现 429 表示建立连接的频率过高。连接后，订阅方案外数据族的频道会收到 op: error（« canal … hors offre : la famille … n’est pas incluse dans votre abonnement »），整个订阅都会被拒绝。见使用限制。

#MCP 服务器

错误遵循同一种格式 Erreur (HTTP NNN) : message，这样智能体只需识别一种情况。每次工具调用都按使用客户端密钥的 REST 请求来判断：方案外数据族的 403 或配额相关的 429 会原样返回，并附带其 detail。有两类错误是它特有的：

• 未知指标：消息会列出四十六个有效指标。
• 定位无效：同时指定两个目标、缺少目标、目标类型错误，或对全市场指标指定了目标。错误会指出所需的参数，并且在任何网络调用之前抛出。

服务器故障会先自动重试一次再报告。超时会在三十秒后返回 Erreur (HTTP 504)。

#重试策略

并非所有请求都可以重放。重放错误的请求只会得到完全相同的响应，白白消耗配额。

def should_retry(code: int) -> bool:
    """What is transient, and what never will be."""
    # 429 and 503 will pass: the server says when.
    if code in (429, 503):
        return True
    # 500: a fault on the service side, a retry makes sense.
    if code == 500:
        return True
    # 400, 403, 422: the request is at fault. Replaying it as is will
    # produce exactly the same response.
    return False

• 遵守 Retry-After，不要自行设定延迟：服务器知道自己何时就绪。
• 限制重试次数。三到四次就够了：再多说明问题不是暂时的。
• 不要重放 4xx（429 除外）。请修正请求。
• 对于数据流，请以递增的延迟重连，并把 4003 关闭视为客户端过载的信号：不改变消费方式就重连，只会再次被断开。