401 Unauthorized 是什么意思？怎么解决？

API Key 错误、缺失或格式不对。确认请求头为 Authorization: Bearer sk-mafdet-…;或重新登录控制台。

missing_runtime_metadata 是什么意思？怎么解决？

用了不带会话元数据的裸 master key 调用。请改用控制台创建的 API Key。

MODEL_NOT_ALLOWED 是什么意思？怎么解决？

当前账号或 Key 无该模型权限。见「权限与模型范围」,或联系管理员开放。

WEB_SEARCH_NOT_ENABLED 是什么意思？怎么解决？

联网搜索为内测能力,当前账号未开通。联系管理员加入白名单。

model_api_surface_mismatch 是什么意思？怎么解决？

该模型不在你调用的端点上运行——例如把 embeddings 模型发给了 /v1/chat/completions。请在「模型调用总览」查看模型所属的 API Surface。该错误在调用 provider 前返回，不产生费用。

request_cost_limit_exceeded 是什么意思？怎么解决？

本次请求的预估成本超过了该 Key 的单请求上限。请缩短输入、调低 max_tokens，或提高 Key 的成本上限。

EMBEDDING_MODALITY_NOT_ENABLED 是什么意思？怎么解决？

gemini-embedding-2 只接受文本。图片或视频请用 multimodal-embedding-1。

EMBEDDING_INPUT_EMPTY 是什么意思？怎么解决？

input 为空。请传入非空字符串或数组。

EMBEDDING_ITEM_TOO_LONG 是什么意思？怎么解决？

单条输入超过 100,000 字符，请拆分后再试。

EMBEDDING_BATCH_TOO_LARGE 是什么意思？怎么解决？

单次超过 100 条输入，请分批（每批 ≤100 条）。

EMBEDDING_INPUT_TOO_LARGE 是什么意思？怎么解决？

输入总量超过 2 MB 请求上限，请减少条数或缩短内容。

EMBEDDING_DIMENSIONS_INVALID 是什么意思？怎么解决？

dimensions 只能是 768、1536 或 3072（默认 3072）。

MM_EMBEDDING_NO_IMAGE 是什么意思？怎么解决？

未找到图片。multimodal-embedding-1 只接受 data:image/...;base64 形式的 data URI——裸 base64 和 image_url 对象都会被拒。

MM_EMBEDDING_MODALITY_NOT_ENABLED 是什么意思？怎么解决？

请求混合了多种模态。请只发图片，或只发一个视频——不能混发，也不能带文本。

MM_EMBEDDING_TOO_MANY_IMAGES 是什么意思？怎么解决？

每次请求最多 8 张图片。

MM_EMBEDDING_NO_VIDEO 是什么意思？怎么解决？

未找到视频。请使用 Vertex 原生形式：{"video": {"bytesBase64Encoded": " "}}——视频不接受 data: URI。

MM_EMBEDDING_TOO_MANY_VIDEOS 是什么意思？怎么解决？

每次请求只能传 1 个视频。

MM_EMBEDDING_VIDEO_TOO_LONG 是什么意思？怎么解决？

视频长度超过首发版本的 6 秒上限，请裁剪后重试。

MM_EMBEDDING_VIDEO_TOO_LARGE 是什么意思？怎么解决？

视频超过 300 KB。仅靠时长不足以判断——很短但高码率的视频同样会超限，请用更低码率重新编码。

MM_EMBEDDING_VIDEO_UNREADABLE 是什么意思？怎么解决？

无法按 mp4 解析该视频，因而无法得知计费所依据的时长。系统选择拒绝，而不是按 0 计费。

VIDEO_EMBEDDING_NOT_ENABLED 是什么意思？怎么解决？

本部署未开放视频嵌入。

TTS_VOICE_NOT_ALLOWED 是什么意思？怎么解决？

不支持该音色。请使用 Gemini 音色——Kore、Puck、Charon、Fenrir 或 Aoede。OpenAI 的音色名（如 alloy）会被拒绝；响应中会列出允许的取值。

TTS_FORMAT_NOT_ALLOWED 是什么意思？怎么解决？

response_format 只能是 wav 或 pcm。

TTS_NOT_ENABLED 是什么意思？怎么解决？

本部署未开放语音合成。

PLAYGROUND_CREDIT_EXHAUSTED 是什么意思？怎么解决？

本周期的 Playground 额度已用尽。可等待下个周期，或购买 $10 加量包；API 钱包不受影响。

PLAYGROUND_REQUEST_EXCEEDS_REMAINING 是什么意思？怎么解决？

这一次请求的花费超过了剩余 Playground 额度，因此被提前拒绝，而不是执行到一半。

insufficient_credit 是什么意思？怎么解决？

余额不足。查看「余额与用量」,或请管理员发放测试额度。

RATE_LIMITED 是什么意思？怎么解决？

触发限流(每分钟请求数、每分钟 token 数或搜索频率)。「稍后重试」只对突发限流有效:单个大请求本身就可能超过每分钟 token 上限——发往 embeddings 接口的视频是 base64(约每 KB 929 token),300 KB 的视频≈279,000 token。这种情况应改用 tpm 更高的套餐下的 Key(视频嵌入实际需要 Pro 及以上),而不是重试。

parallel_limit_exceeded 是什么意思？怎么解决？

并发请求数超限。减少同时进行的请求。

FILE_TOO_LARGE 是什么意思？怎么解决？

文件超过单文件 50 MB 上限。注意:原生媒体(图片 / 音频 / 视频)内联发送时上限更低,为 15 MB;直接调用 API 时整个请求体需小于 25 MB。

FILE_EMPTY 是什么意思？怎么解决？

文件无可提取文字(如扫描版 PDF / 无文字图片)。换文字型文件。

FILE_TEXT_DECODE_FAILED 是什么意思？怎么解决？

文件损坏或无法解析(如加密 PDF)。检查文件后重试。

QUERY_BLOCKED 是什么意思？怎么解决？

搜索/输入中检测到疑似 secret(私钥、token 等),已拦截。移除敏感内容。

PROVIDER_UNAVAILABLE 是什么意思？怎么解决？

上游 provider 暂时不可用。稍后重试;持续不可用请联系管理员。

错误码与排障

调用失败时,响应里会带一个错误码。下表按类别说明含义与处理方法。

认证错误

错误码	HTTP	含义与处理
`401 Unauthorized`	401	API Key 错误、缺失或格式不对。确认请求头为 Authorization: Bearer sk-mafdet-…;或重新登录控制台。
`missing_runtime_metadata`	400	用了不带会话元数据的裸 master key 调用。请改用控制台创建的 API Key。

权限错误

错误码	HTTP	含义与处理
`MODEL_NOT_ALLOWED`	403	当前账号或 Key 无该模型权限。见「权限与模型范围」,或联系管理员开放。
`WEB_SEARCH_NOT_ENABLED`	403	联网搜索为内测能力,当前账号未开通。联系管理员加入白名单。

请求校验

错误码	HTTP	含义与处理
`model_api_surface_mismatch`	400	该模型不在你调用的端点上运行——例如把 embeddings 模型发给了 /v1/chat/completions。请在「模型调用总览」查看模型所属的 API Surface。该错误在调用 provider 前返回，不产生费用。
`request_cost_limit_exceeded`	400	本次请求的预估成本超过了该 Key 的单请求上限。请缩短输入、调低 max_tokens，或提高 Key 的成本上限。
`EMBEDDING_MODALITY_NOT_ENABLED`	400	gemini-embedding-2 只接受文本。图片或视频请用 multimodal-embedding-1。
`EMBEDDING_INPUT_EMPTY`	400	input 为空。请传入非空字符串或数组。
`EMBEDDING_ITEM_TOO_LONG`	400	单条输入超过 100,000 字符，请拆分后再试。
`EMBEDDING_BATCH_TOO_LARGE`	400	单次超过 100 条输入，请分批（每批 ≤100 条）。
`EMBEDDING_INPUT_TOO_LARGE`	400	输入总量超过 2 MB 请求上限，请减少条数或缩短内容。
`EMBEDDING_DIMENSIONS_INVALID`	400	dimensions 只能是 768、1536 或 3072（默认 3072）。
`MM_EMBEDDING_NO_IMAGE`	400	未找到图片。multimodal-embedding-1 只接受 data:image/...;base64 形式的 data URI——裸 base64 和 image_url 对象都会被拒。
`MM_EMBEDDING_MODALITY_NOT_ENABLED`	400	请求混合了多种模态。请只发图片，或只发一个视频——不能混发，也不能带文本。
`MM_EMBEDDING_TOO_MANY_IMAGES`	400	每次请求最多 8 张图片。
`MM_EMBEDDING_NO_VIDEO`	400	未找到视频。请使用 Vertex 原生形式：{"video": {"bytesBase64Encoded": "<裸 base64>"}}——视频不接受 data: URI。
`MM_EMBEDDING_TOO_MANY_VIDEOS`	400	每次请求只能传 1 个视频。
`MM_EMBEDDING_VIDEO_TOO_LONG`	400	视频长度超过首发版本的 6 秒上限，请裁剪后重试。
`MM_EMBEDDING_VIDEO_TOO_LARGE`	400	视频超过 300 KB。仅靠时长不足以判断——很短但高码率的视频同样会超限，请用更低码率重新编码。
`MM_EMBEDDING_VIDEO_UNREADABLE`	400	无法按 mp4 解析该视频，因而无法得知计费所依据的时长。系统选择拒绝，而不是按 0 计费。
`VIDEO_EMBEDDING_NOT_ENABLED`	400	本部署未开放视频嵌入。
`TTS_INPUT_REQUIRED`	400	input 缺失或为空。
`TTS_INPUT_TOO_LONG`	400	input 超过 5,000 字符。
`TTS_VOICE_REQUIRED`	400	必须提供 voice。
`TTS_VOICE_NOT_ALLOWED`	400	不支持该音色。请使用 Gemini 音色——Kore、Puck、Charon、Fenrir 或 Aoede。OpenAI 的音色名（如 alloy）会被拒绝；响应中会列出允许的取值。
`TTS_FORMAT_NOT_ALLOWED`	400	response_format 只能是 wav 或 pcm。
`TTS_NOT_ENABLED`	400	本部署未开放语音合成。

余额错误

错误码	HTTP	含义与处理
`PLAYGROUND_CREDIT_EXHAUSTED`	402	本周期的 Playground 额度已用尽。可等待下个周期，或购买 $10 加量包；API 钱包不受影响。
`PLAYGROUND_REQUEST_EXCEEDS_REMAINING`	402	这一次请求的花费超过了剩余 Playground 额度，因此被提前拒绝，而不是执行到一半。
`insufficient_credit`	402	余额不足。查看「余额与用量」,或请管理员发放测试额度。

限流错误

错误码	HTTP	含义与处理
`RATE_LIMITED`	429	触发限流(每分钟请求数、每分钟 token 数或搜索频率)。「稍后重试」只对突发限流有效:单个大请求本身就可能超过每分钟 token 上限——发往 embeddings 接口的视频是 base64(约每 KB 929 token),300 KB 的视频≈279,000 token。这种情况应改用 tpm 更高的套餐下的 Key(视频嵌入实际需要 Pro 及以上),而不是重试。
`parallel_limit_exceeded`	429	并发请求数超限。减少同时进行的请求。

文件上传错误

错误码	HTTP	含义与处理
`FILE_TOO_LARGE`	400	文件超过单文件 50 MB 上限。注意:原生媒体(图片 / 音频 / 视频)内联发送时上限更低,为 15 MB;直接调用 API 时整个请求体需小于 25 MB。
`FILE_EMPTY`	400	文件无可提取文字(如扫描版 PDF / 无文字图片)。换文字型文件。
`FILE_TEXT_DECODE_FAILED`	400	文件损坏或无法解析(如加密 PDF)。检查文件后重试。
`QUERY_BLOCKED`	403	搜索/输入中检测到疑似 secret(私钥、token 等),已拦截。移除敏感内容。

上游 / Provider 错误

错误码	HTTP	含义与处理
`PROVIDER_UNAVAILABLE`	503	上游 provider 暂时不可用。稍后重试;持续不可用请联系管理员。

还没解决？

模型相关：确认 model 是有效的模型 ID
权限相关：见权限与模型范围
余额相关：见余额与用量
配置相关：见 OpenAI 兼容工具