错误响应格式
大多数错误返回一个带有人类可读消息的error 字段:
{
"error": "Invalid request parameters"
}
{
"error": "Your generation was blocked due to the model provider's content policies. Credits have been refunded.",
"credits_refunded": true
}
details 和 issues 字段:
{
"error": "Invalid request parameters",
"details": {
"_errors": [],
"field": {
"_errors": ["Field is required"]
}
},
"issues": []
}
{
"error": {
"message": "Your request exceeds the model's maximum context. Please reduce your prompt or completion length.",
"type": "invalid_request_error",
"param": "messages",
"code": "context_length_exceeded"
}
}
缺少凭据
不带任何凭据的请求会返回402 Payment Required,而不是 401。每个付费路由也都接受 x402 钱包认证,因此响应是一个支付质询:它包含 PAYMENT-REQUIRED 响应头,以及描述两种认证方式的响应体。
{
"x402Version": 2,
"error": "Authentication required",
"accepts": [ ... ],
"authOptions": {
"apiKey": {
"header": "Authorization: Bearer YOUR_API_KEY",
"getKey": "https://venice.ai/settings/api"
},
"x402Wallet": {
"header": "SIGN-IN-WITH-X",
"topUp": "POST /api/v1/x402/top-up"
}
}
}
Authorization: Bearer 请求头。存在但无效的密钥会返回 401。
请求格式错误
这些错误产生于读取请求体阶段,早于任何端点专属的校验。| HTTP 状态 | 消息 | 原因 |
|---|---|---|
| 400 | 'Content-Type' must be 'application/json' | 发送 POST、PUT 或 PATCH 请求体时未设置 Content-Type: application/json。接受文件上传的端点也接受 multipart/form-data |
| 400 | Invalid JSON request | 请求体不是有效的 JSON |
| 400 | Invalid multipart request: malformed part header | 无法解析的 multipart/form-data 请求体 |
| 413 | Request body exceeds the maximum allowed size. | 请求体过大 |
| 415 | Request encoding is not supported | API 无法解码的 Content-Encoding 或字符集 |
Content-Type 返回 400,而不是 415。因大小限制返回的 413 响应还包含一个 code 字段:
{
"code": "PAYLOAD_TOO_LARGE",
"error": "Request body exceeds the maximum allowed size."
}
错误码
| 错误码 | HTTP 状态 | 消息 | 日志级别 |
|---|---|---|---|
AUTHENTICATION_FAILED | 401 | Authentication failed | - |
AUTHENTICATION_FAILED_INACTIVE_KEY | 401 | Authentication failed - Pro subscription is inactive. Please upgrade your subscription to continue using the API | - |
X402_INVALID_SIGN_IN | 401 | Invalid Sign-in-with-x signature | - |
PRO_ONLY_MODEL | 401 | This model is only available to Pro users | - |
INSUFFICIENT_BALANCE | 402 | Insufficient USD or Diem balance to complete request. Visit https://venice.ai/settings/api to add credits. | - |
API_KEY_DIEM_SPEND_LIMIT_EXCEEDED | 402 | API key DIEM spend limit exceeded. Your account may still have DIEM balance, but this API key has reached its configured DIEM spending limit. | - |
API_KEY_USD_SPEND_LIMIT_EXCEEDED | 402 | API key USD spend limit exceeded. Your account may still have USD balance, but this API key has reached its configured USD spending limit. | - |
UNAUTHORIZED | 403 | Unauthorized access | - |
API_ACCESS_DISABLED | 403 | API access has been disabled for this account. Please contact [email protected] | - |
X402_WALLET_MISMATCH | 403 | You can only access resources for your own wallet | - |
INVALID_REQUEST | 400 | Invalid request parameters | - |
INVALID_MODEL | 400 | Invalid model specified | - |
REQUEST_ID_NOT_FOUND | 400 | Request ID is invalid. | - |
INVALID_AUDIO_FORMAT | 400 | Invalid audio format. Supported formats are WAV and MP3. | - |
INVALID_VIDEO_FORMAT | 400 | Invalid video format. Supported formats include MP4, MOV, WebM, MKV, AVI, and others. | - |
CORRUPTED_IMAGE | 400 | The image file is corrupted or unreadable | - |
IMAGE_TOO_SMALL | 400 | Image dimensions are too small | - |
TOO_MANY_TOKENS | 400 | Your request exceeds the model’s maximum context. Please reduce your prompt or completion length. | - |
CHARACTER_NOT_FOUND | 404 | No character could be found from the provided character_slug | - |
MODEL_NOT_FOUND | 404 | Specified model not found | - |
MEDIA_NOT_FOUND | 404 | Media could not be found. Request may be invalid, expired, or deleted. | - |
PAYLOAD_TOO_LARGE | 413 | The request payload is too large. Please reduce the size of your request. | - |
INVALID_CONTENT_TYPE | 415 | Invalid request content-type。仅由 /image/multi-edit 返回 | - |
VIDEO_DURATION_TOO_LONG | 422 | Video duration exceeds the maximum allowed. | - |
VIDEO_DURATION_TOO_SHORT | 422 | Video duration is too short. | - |
IMAGE_TOO_LARGE | 422 | Image dimensions exceed the maximum allowed. | - |
CONTENT_POLICY_VIOLATION | 422 | Your prompt violates the content policy of Venice.ai or the model provider | - |
ASR_UPSTREAM_VALIDATION_FAILED | 422 | The audio could not be processed for transcription. Common causes: zero-length, silent, corrupt, or unsupported-language audio. Please verify the file and retry. | warn |
RATE_LIMIT_EXCEEDED | 429 | Rate limit exceeded | - |
MODEL_OVERLOADED | 429 | The model is currently overloaded. Please try again later. | - |
INFERENCE_FAILED | 500 | Inference processing failed | error |
UPSCALE_FAILED | 500 | Image upscaling failed | error |
IMAGE_EDIT_ERROR | 500 | Image edit failed | error |
UNKNOWN_ERROR | 500 | An unknown error occurred | error |
TEE_ATTESTATION_FAILED | 502 | TEE attestation request failed. The Trusted Execution Environment provider may be temporarily unavailable. | error |
TEE_SIGNATURE_FAILED | 502 | TEE signature request failed. The Trusted Execution Environment provider may be temporarily unavailable. | error |
ASR_UPSTREAM_FAILED | 502 | Audio transcription failed due to a temporary upstream error. Please retry. | warn |
MODEL_OFFLINE | 503 | The model is temporarily offline. Please try again later. | - |
MODEL_AT_CAPACITY | 503 | The model is at capacity. Please try again later. | - |
REQUEST_TIMEOUT | 504 | The request took too long to complete and was timed-out. For non-streaming requests, use the streaming API by setting stream=true. A streaming chat completion that times out before the model’s first chunk reports the failure as an in-band SSE error frame instead. | - |
其他错误
上表并不详尽。部分错误返回时不带已列出的错误码,且消息内容可能因模型和端点而异,因此请根据 HTTP 状态而非消息文本进行分支处理。可能遇到但未列入上表的错误:| HTTP 状态 | 发生场景 |
|---|---|
| 400 | 聊天或 Responses 请求中的图像输入格式不受支持 |
| 400 | 所请求的语音不适用于该文本转语音模型 |
| 403 | 请求来自不在 API 密钥允许列表中的 IP 地址 |
| 403 | API 密钥的隐私设置不允许使用所请求的模型 |
| 403 | 对所请求模型的访问受到限制。请联系 [email protected] |
| 409 | 获取视频、音乐或变声结果时,结果仍在上传中。请稍后重试 |
| 410 | 该端点已停用 |
| 422 | 音频过长或过短(语音克隆、变声和音频任务) |
| 422 | 视频请求的输入图像宽高比超出模型可接受的范围 |
| 422 | 视频请求的输入被内容审核拦截 |
| 500 | 视频或变声生成失败 |
| 502 | 上游语音合成失败,或无法获取已生成的视频。请重试该请求 |