ModelRiver 使用结构化错误响应，帮助你快速定位并解决问题。根据你所使用的 API 形式，错误结构会有所不同。
OpenAI 兼容错误格式
当你使用 OpenAI 兼容层 时，错误会遵循标准 OpenAI 错误包结构：
JSON
1{2 "error": {3 "message": "Workflow 'xyz' does not exist. Create it in the console first.",4 "type": "invalid_request_error",5 "param": "model",6 "code": "model_not_found"7 }8}常见错误码
| HTTP | Code | 含义 |
|---|---|---|
| 400 | invalid_request_error | 参数缺失或无效 |
| 401 | authentication_error | API key 无效或缺失 |
| 404 | model_not_found | 工作流不存在 |
| 400 | model_not_supported | 当前工作流为事件驱动，请改用异步 API |
| 429 | rate_limit_exceeded | 请求过多，需要退避重试 |
| 502 | upstream_error | 上游供应商返回错误 |
| 503 | service_unavailable | 功能不可用或内部失败 |
原生 API 错误格式
使用原生 ModelRiver API（/v1/ai）时，错误会以 wrapped 格式返回：
JSON
1{2 "data": null,3 "customer_data": {},4 "error": {5 "message": "Provider request failed",6 "details": {"status": 504, "message": "Upstream timeout"}7 },8 "meta": {9 "status": "error",10 "http_status": 502,11 "workflow": "marketing-summary",12 "attempts": [13 {"provider": "openai", "model": "gpt-4o-mini", "status": "error", "reason": "timeout"}14 ]15 }16}注意： 当请求本身有效但供应商失败时，ModelRiver 会返回
200并在正文中携带error对象。传输或认证问题仍返回标准 HTTP 状态码。
常见错误场景
认证错误（401）
常见原因：API key 过期、已吊销、格式错误，或者缺少 Bearer 前缀。
工作流不存在（404）
常见原因：工作流名称不匹配、大小写错误，或者当前 API key 不属于该工作流所在项目。
事件驱动工作流错误（400）
如果工作流配置了 event_name，它不能用于同步 chat completions 端点，应改用 POST /v1/ai/async。
供应商错误（502）
当上游超时、限流或故障时，可通过 meta.attempts 查看每次尝试的供应商、模型与失败原因。
速率限制（429）
当超出计划限制时，服务会返回 429。应在客户端实现指数退避，并结合工作流中的回退供应商降低失败率。
重试策略
建议重试的错误
4295xx- 上游超时
- 可恢复的网络错误
不建议直接重试的错误
- API key 无效
- 工作流不存在
- 请求参数无效
- 权限不足
最佳实践
- 始终查看
meta.attempts - 对
429和5xx使用指数退避 - 在工作流中配置回退供应商
- 把
error.details与meta.attempts写入日志 - 前端展示可理解的错误文案，而不是原始 payload
- 配置客户端超时，避免无限等待
- 在可观测性中跟踪错误率和异常模式