API 调用 5 个常见错误，避坑指南

前言调 API 时遇到报错是常事。这篇文章列 5 个最常见错误每个都附正确做法。代码示例用 Python但思路适用于其他语言。错误 1没设置超时导致请求卡死不设置超时请求可能挂起几十分钟不返回任务堆积最终资源耗尽。❌ 错误不设置超时response requests.post(API_URL, jsonpayload)可能卡住等很久✅ 正确设置合理超时response requests.post(API_URL, jsonpayload, timeout30)30 秒未返回则抛出 timeout 异常超时时间建议 30 秒。短任务可以 10 秒长任务可以 60 秒。太短容易误杀正常请求太长会让卡死请求堆积。错误 2API Key 写在代码里把 API Key 直接写在代码里会上传到代码仓库一旦泄露需要立刻重置。❌ 错误API Key 硬编码API_KEY “sk-abc123xyz456”client OpenAI(api_keyAPI_KEY)✅ 正确从环境变量读取import osAPI_KEY os.environ.get(“DEEPSEEK_API_KEY”)if not API_KEY:raise ValueError(“请设置环境变量 DEEPSEEK_API_KEY”)client OpenAI(api_keyAPI_KEY)更安全的做法是用密钥管理服务如 AWS Secrets Manager、HashiCorp Vault。至少做到 API Key 不进代码仓库。错误 3不处理 429 限流高并发调用 API 时容易触发 429Too Many Requests。如果不处理整个流程会中断。❌ 错误遇到 429 直接失败response requests.post(API_URL, jsonpayload)if response.status_code 200:return response.json()429 直接抛异常任务中断✅ 正确429 时重试带退避import timedef call_with_retry(payload, max_retries3):for attempt in range(max_retries):response requests.post(API_URL, jsonpayload, timeout30)if response.status_code 200:return response.json()if response.status_code 429:# 指数退避1 秒、2 秒、4 秒wait 2 ** attemptprint(f429 限流等待 {wait} 秒后重试)time.sleep(wait)else:response.raise_for_status()raise Exception(“重试 3 次仍失败”)429 是 API 服务方的限流保护。处理方式是退避后重试不是放弃。OpenStarry Coding Plan 的 5 小时限额也是类似的限流机制参考相关阅读。错误 4不限制 max_tokens 导致账单爆掉如果调用时不限制 max_tokens模型可能输出几千字单次调用就花掉几块钱。批量任务时账单会失控。❌ 错误不限制 max_tokenspayload {“model”: “deepseek-chat”,“messages”: [{“role”: “user”, “content”: prompt}]}模型可能输出几千字✅ 正确根据需要设置 max_tokenspayload {“model”: “deepseek-chat”,“messages”: [{“role”: “user”, “content”: prompt}],“max_tokens”: 500 # 限制最多 500 token 输出}max_tokens 不是越多越好按实际需要设置。文本摘要设 200-500问答设 500-1000长文生成才需要 2000。错误 5模型名拼写错误模型名是字符串写错一个字符就报错。常见错误大小写错、多空格、用全角字符。❌ 错误模型名拼错models [“deepseek-chat”, # 正确“DeepSeek-Chat”, # 大小写错 deepseek-chat , # 多空格deepseek-chat , # 末尾空格“deepseek_chat”, # 下划线错应该是连字符]✅ 正确用常量定义避免拼写错误from enum import Enumclass ModelName(str, Enum):DEEPSEEK_CHAT “deepseek-chat”DEEPSEEK_REASONER “deepseek-reasoner”GLM_5 “GLM-5.2”KIMI_K2_6 “kimi-k2-6”使用payload {“model”: ModelName.DEEPSEEK_CHAT.value, …}用枚举或常量集中管理模型名避免到处复制粘贴字符串导致拼写错误。写在最后5 个错误都是真实项目里常见的。避坑的核心思路超时设置保护资源密钥管理保护账号限流处理保护流程参数限制保护账单字符串管理保护开发调 API 不难难的是把所有边界情况都处理好。把这 5 个错误记住能避开 80% 的常见问题。相关阅读DeepSeek API 高峰时段排队慢这套调度脚本能解决Meta Muse Spark 1.1多智能体协作能做到什么你调 API 时最常踩的坑是什么评论区聊聊。