API 调用 5 个常见错误，避坑指南-拓冰建站

前言
调 API 时遇到报错是常事。这篇文章列 5 个最常见错误，每个都附正确做法。代码示例用 Python，但思路适用于其他语言。

错误 1：没设置超时导致请求卡死
不设置超时，请求可能挂起几十分钟不返回，任务堆积，最终资源耗尽。

❌ 错误：不设置超时

response = requests.post(API_URL, json=payload)

可能卡住等很久

✅ 正确：设置合理超时

response = requests.post(API_URL, json=payload, timeout=30)

30 秒未返回则抛出 timeout 异常

超时时间建议 30 秒。短任务可以 10 秒，长任务可以 60 秒。太短容易误杀正常请求，太长会让卡死请求堆积。

错误 2：API Key 写在代码里
把 API Key 直接写在代码里会上传到代码仓库，一旦泄露需要立刻重置。

❌ 错误：API Key 硬编码

API_KEY = “sk-abc123xyz456”
client = OpenAI(api_key=API_KEY)

✅ 正确：从环境变量读取

import os
API_KEY = os.environ.get(“DEEPSEEK_API_KEY”)
if not API_KEY:
raise ValueError(“请设置环境变量 DEEPSEEK_API_KEY”)
client = OpenAI(api_key=API_KEY)
更安全的做法是用密钥管理服务（如 AWS Secrets Manager、HashiCorp Vault）。至少做到 API Key 不进代码仓库。

错误 3：不处理 429 限流
高并发调用 API 时容易触发 429（Too Many Requests）。如果不处理，整个流程会中断。

❌ 错误：遇到 429 直接失败

response = requests.post(API_URL, json=payload)
if response.status_code == 200:
return response.json()

429 直接抛异常，任务中断

✅ 正确：429 时重试，带退避

import time

def call_with_retry(payload, max_retries=3):
for attempt in range(max_retries):
response = requests.post(API_URL, json=payload, timeout=30)
if response.status_code == 200:
return response.json()
if response.status_code == 429:
# 指数退避：1 秒、2 秒、4 秒
wait = 2 ** attempt
print(f"429 限流，等待 {wait} 秒后重试")
time.sleep(wait)
else:
response.raise_for_status()
raise Exception(“重试 3 次仍失败”)
429 是 API 服务方的限流保护。处理方式是退避后重试，不是放弃。OpenStarry Coding Plan 的 5 小时限额也是类似的限流机制（参考相关阅读）。

错误 4：不限制 max_tokens 导致账单爆掉
如果调用时不限制 max_tokens，模型可能输出几千字，单次调用就花掉几块钱。批量任务时账单会失控。

❌ 错误：不限制 max_tokens

payload = {
“model”: “deepseek-chat”,
“messages”: [{“role”: “user”, “content”: prompt}]
}

模型可能输出几千字

✅ 正确：根据需要设置 max_tokens

payload = {
“model”: “deepseek-chat”,
“messages”: [{“role”: “user”, “content”: prompt}],
“max_tokens”: 500 # 限制最多 500 token 输出
}
max_tokens 不是越多越好，按实际需要设置。文本摘要设 200-500，问答设 500-1000，长文生成才需要 2000+。

错误 5：模型名拼写错误
模型名是字符串，写错一个字符就报错。常见错误：大小写错、多空格、用全角字符。