原创教程官方文档整理

Jev Python 调用失败怎么办：超时、重试和错误状态分开记

有限重试的调用边界与可持久查询的任务状态设计。

适用场景按官方 Python SDK 配置有限重试，区分认证错误、超时和响应结构错误，记录请求 ID，并让刷新与重复提交能读取任务状态。

来源 · JevLog 编辑部Intermediate15 分钟

开始阅读

按官方 Python SDK 配置有限重试，区分认证错误、超时和响应结构错误，记录请求 ID，并让刷新与重复提交能读取任务状态。

来源 · JevLog 编辑部 · 本站原创

原文封面 · TypeSafe AI

原文封面 · TypeSafe AI

2026-10-02 新增：依据当前官方文档整理，附本站编写练习。未做真实服务调用；来源首次发布日期未确认。

背景 / 问题

“处理中”永不结束，或把 HTTP 失败当低置信度，会使用户无从重试。调用层需要明确终态；模型不确定、传输故障和配置错误要分开记。

准备与来源

安装 typesafe-sdk，在服务端设置 TYPESAFE_API_KEY。下载 retry-scenarios.json，它只是状态清单，不调用服务。
SDK、网关、工作流选一个主要重试层，设总预算，避免重试次数相乘。
官方文档
官方文档
官方文档

JevLog 原创流程图，非产品截图或实测结果。

JevLog 原创流程图，非产品截图或实测结果。

操作步骤

1. 按错误分类，不盲重试

401/403 先修凭据和权限，400/422 修输入。429 与临时 5xx 才考虑有限重试。响应结构错了仍是错误，不能默认类别来凑成功结果。清单包含超时、认证、限流和重复提交情况。

2. 次数、请求超时、总预算分开

max_retries=1 是初次调用后最多再试一次；RetryPolicy.timeout 包含初次尝试和等待的总重试预算。client timeout 是请求超时。以下是演示预算，要按服务约束与页面体验调整，不是速度承诺。

from typesafe_sdk import (TypeSafeClient, Choice, RetryPolicy, TypeSafeError,
 TypeSafeAPIError, TypeSafeAPITimeoutError, TypeSafeAPIResponseValidationError)

def classify(state):
 try:
  with TypeSafeClient(timeout=5.0, retry=RetryPolicy(max_retries=1,
    backoff_initial=0.5, backoff_max=1.0, timeout=12.0,
    respect_retry_after=True)) as client:
   result = client.system_one(state, {"category": Choice(
    instructions="Classify this report",
    criteria={"bug":"Software malfunction","other":"Other"})})
   return {"status":"succeeded","choice":result.choices["category"].choice}
 except TypeSafeAPITimeoutError:
  return {"status":"retryable_error","reason":"timeout"}
 except TypeSafeAPIResponseValidationError:
  return {"status":"invalid_response"}
 except TypeSafeAPIError as error:
  retryable = error.status in (408,429) or error.status >= 500
  return {"status":"retryable_error" if retryable else "request_error",
          "http_status":error.status,"request_id":error.request_id}
 except TypeSafeError:
  return {"status":"configuration_or_connection_error"}

3. 用任务 ID 保存页面状态

提交创建 job_id，持久写 running，所有成功和异常分支写终态。按钮禁用只解决当前页重复点击；刷新按 job_id 读取。应用请求键判断同次提交是否复用，不声称上游 API 自带幂等。

4. 重试函数只做分类

发消息、创建工单和扣费放在单独执行阶段，用数据库唯一键或下游明确支持的幂等键防重复。超时意味着结果未知，不证明上游没有处理；后续动作不能随分类重试再做一遍。

5. 预算耗尽也要能交接

记录任务 ID、问题版本、耗时、状态与 request_id，不写密钥和完整客户消息。展示“未完成，可重试”，关联旧任务与重试任务。本站未调用 API，上线前用自己的账号确认版本和限流行为。

练习样例：下载 retry-scenarios.json，可在本地练习；非本站实测结果。

结果与注意