What does 401 Unauthorized mean and how do I fix it?

API key is wrong, missing, or malformed. Ensure the header is Authorization: Bearer sk-mafdet-…; or sign in to the console again.

What does missing_runtime_metadata mean and how do I fix it?

Called with a bare master key that has no session metadata. Use an API key created in the console.

What does MODEL_NOT_ALLOWED mean and how do I fix it?

Your account or key has no access to this model. See Permissions & model scope, or ask an admin to grant access.

What does WEB_SEARCH_NOT_ENABLED mean and how do I fix it?

Web search is a beta capability not enabled for your account. Ask an admin to whitelist you.

What does model_api_surface_mismatch mean and how do I fix it?

This model does not run on the endpoint you called — for example an embeddings model sent to /v1/chat/completions. Check the model's API surface on Models overview. Rejected before the provider is called, so nothing is charged.

What does request_cost_limit_exceeded mean and how do I fix it?

The estimated cost of this single request exceeds the per-request cap on your key. Shorten the input, lower max_tokens, or raise the key's cost cap.

What does EMBEDDING_MODALITY_NOT_ENABLED mean and how do I fix it?

gemini-embedding-2 takes text only. Use multimodal-embedding-1 for images or video.

What does EMBEDDING_INPUT_EMPTY mean and how do I fix it?

input was empty. Send a non-empty string or array.

What does EMBEDDING_ITEM_TOO_LONG mean and how do I fix it?

A single input exceeds 100,000 characters. Split it into smaller items.

What does EMBEDDING_BATCH_TOO_LARGE mean and how do I fix it?

More than 100 inputs in one call. Send them in batches of 100 or fewer.

What does EMBEDDING_INPUT_TOO_LARGE mean and how do I fix it?

The combined input exceeds the 2 MB request limit. Send fewer or shorter items.

What does EMBEDDING_DIMENSIONS_INVALID mean and how do I fix it?

dimensions must be 768, 1536 or 3072 (default 3072).

What does MM_EMBEDDING_NO_IMAGE mean and how do I fix it?

No image found. multimodal-embedding-1 accepts images only as data:image/...;base64 data URIs — plain base64 and image_url objects are rejected.

What does MM_EMBEDDING_MODALITY_NOT_ENABLED mean and how do I fix it?

The request mixed modalities. Send images only, or one video only — not both, and not text.

What does MM_EMBEDDING_NO_VIDEO mean and how do I fix it?

No video found. Send it in the Vertex-native form: {"video": {"bytesBase64Encoded": " "}} — a data: URI is not accepted for video.

What does MM_EMBEDDING_VIDEO_TOO_LONG mean and how do I fix it?

The clip is longer than the 6-second limit of this first release. Trim it and retry.

What does MM_EMBEDDING_VIDEO_TOO_LARGE mean and how do I fix it?

The clip is larger than 300 KB. Duration alone is not enough — a short high-bitrate clip can still exceed it. Re-encode at a lower bitrate.

What does MM_EMBEDDING_VIDEO_UNREADABLE mean and how do I fix it?

The video could not be read as an mp4, so its duration (what you are billed on) is unknown. It is refused rather than billed as zero.

What does VIDEO_EMBEDDING_NOT_ENABLED mean and how do I fix it?

Video embedding is not enabled for this deployment.

What does TTS_INPUT_TOO_LONG mean and how do I fix it?

input exceeds 5,000 characters.

What does TTS_VOICE_NOT_ALLOWED mean and how do I fix it?

Not a supported voice. Use a Gemini voice — Kore, Puck, Charon, Fenrir or Aoede. OpenAI voice names such as alloy are rejected; the response lists the allowed values.

What does TTS_FORMAT_NOT_ALLOWED mean and how do I fix it?

response_format must be wav or pcm.

What does TTS_NOT_ENABLED mean and how do I fix it?

Text to speech is not enabled for this deployment.

What does PLAYGROUND_CREDIT_EXHAUSTED mean and how do I fix it?

This period's Playground credit is used up. Wait for the next period or buy a $10 top-up; your API wallet is unaffected.

What does PLAYGROUND_REQUEST_EXCEEDS_REMAINING mean and how do I fix it?

This single request costs more than your remaining Playground credit, so it was refused up front rather than half-run.

What does insufficient_credit mean and how do I fix it?

Out of balance. See Balance & usage, or ask an admin to grant test credit.

What does RATE_LIMITED mean and how do I fix it?

Rate limited by requests per minute, tokens per minute, or search frequency. Retrying later only helps for burst limits: a single large request can exceed the per-minute token limit on its own — a video sent to the embeddings API is base64 (~929 tokens per KB), so a 300 KB clip is ~279,000 tokens. In that case use a key on a plan with a higher tpm (video embedding effectively needs Pro or above) rather than retrying.

What does parallel_limit_exceeded mean and how do I fix it?

Too many concurrent requests. Reduce requests in flight.

What does FILE_TOO_LARGE mean and how do I fix it?

File exceeds the 50 MB per-file limit. Note that native media (image / audio / video) sent inline has a lower 15 MB ceiling, and a direct API request body must stay under 25 MB.

What does FILE_EMPTY mean and how do I fix it?

No extractable text (e.g. scanned PDF / image with no text). Use a text-based file.

What does FILE_TEXT_DECODE_FAILED mean and how do I fix it?

File is corrupted or can't be parsed (e.g. encrypted PDF). Check the file and retry.

What does QUERY_BLOCKED mean and how do I fix it?

A suspected secret (private key, token, etc.) was detected in the input and blocked. Remove sensitive content.

What does PROVIDER_UNAVAILABLE mean and how do I fix it?

The upstream provider is temporarily unavailable. Retry later; if it persists, contact an admin.

Errors & troubleshooting

When a call fails, the response carries an error code. The tables below explain each one by category.

Authentication errors

Code	HTTP	Meaning & fix
`401 Unauthorized`	401	API key is wrong, missing, or malformed. Ensure the header is Authorization: Bearer sk-mafdet-…; or sign in to the console again.
`missing_runtime_metadata`	400	Called with a bare master key that has no session metadata. Use an API key created in the console.

Permission errors

Code	HTTP	Meaning & fix
`MODEL_NOT_ALLOWED`	403	Your account or key has no access to this model. See Permissions & model scope, or ask an admin to grant access.
`WEB_SEARCH_NOT_ENABLED`	403	Web search is a beta capability not enabled for your account. Ask an admin to whitelist you.

Request validation

Code	HTTP	Meaning & fix
`model_api_surface_mismatch`	400	This model does not run on the endpoint you called — for example an embeddings model sent to /v1/chat/completions. Check the model's API surface on Models overview. Rejected before the provider is called, so nothing is charged.
`request_cost_limit_exceeded`	400	The estimated cost of this single request exceeds the per-request cap on your key. Shorten the input, lower max_tokens, or raise the key's cost cap.
`EMBEDDING_MODALITY_NOT_ENABLED`	400	gemini-embedding-2 takes text only. Use multimodal-embedding-1 for images or video.
`EMBEDDING_INPUT_EMPTY`	400	input was empty. Send a non-empty string or array.
`EMBEDDING_ITEM_TOO_LONG`	400	A single input exceeds 100,000 characters. Split it into smaller items.
`EMBEDDING_BATCH_TOO_LARGE`	400	More than 100 inputs in one call. Send them in batches of 100 or fewer.
`EMBEDDING_INPUT_TOO_LARGE`	400	The combined input exceeds the 2 MB request limit. Send fewer or shorter items.
`EMBEDDING_DIMENSIONS_INVALID`	400	dimensions must be 768, 1536 or 3072 (default 3072).
`MM_EMBEDDING_NO_IMAGE`	400	No image found. multimodal-embedding-1 accepts images only as data:image/...;base64 data URIs — plain base64 and image_url objects are rejected.
`MM_EMBEDDING_MODALITY_NOT_ENABLED`	400	The request mixed modalities. Send images only, or one video only — not both, and not text.
`MM_EMBEDDING_TOO_MANY_IMAGES`	400	At most 8 images per request.
`MM_EMBEDDING_NO_VIDEO`	400	No video found. Send it in the Vertex-native form: {"video": {"bytesBase64Encoded": "<raw base64>"}} — a data: URI is not accepted for video.
`MM_EMBEDDING_TOO_MANY_VIDEOS`	400	One video per request.
`MM_EMBEDDING_VIDEO_TOO_LONG`	400	The clip is longer than the 6-second limit of this first release. Trim it and retry.
`MM_EMBEDDING_VIDEO_TOO_LARGE`	400	The clip is larger than 300 KB. Duration alone is not enough — a short high-bitrate clip can still exceed it. Re-encode at a lower bitrate.
`MM_EMBEDDING_VIDEO_UNREADABLE`	400	The video could not be read as an mp4, so its duration (what you are billed on) is unknown. It is refused rather than billed as zero.
`VIDEO_EMBEDDING_NOT_ENABLED`	400	Video embedding is not enabled for this deployment.
`TTS_INPUT_REQUIRED`	400	input is missing or empty.
`TTS_INPUT_TOO_LONG`	400	input exceeds 5,000 characters.
`TTS_VOICE_REQUIRED`	400	voice is required.
`TTS_VOICE_NOT_ALLOWED`	400	Not a supported voice. Use a Gemini voice — Kore, Puck, Charon, Fenrir or Aoede. OpenAI voice names such as alloy are rejected; the response lists the allowed values.
`TTS_FORMAT_NOT_ALLOWED`	400	response_format must be wav or pcm.
`TTS_NOT_ENABLED`	400	Text to speech is not enabled for this deployment.

Balance errors

Code	HTTP	Meaning & fix
`PLAYGROUND_CREDIT_EXHAUSTED`	402	This period's Playground credit is used up. Wait for the next period or buy a $10 top-up; your API wallet is unaffected.
`PLAYGROUND_REQUEST_EXCEEDS_REMAINING`	402	This single request costs more than your remaining Playground credit, so it was refused up front rather than half-run.
`insufficient_credit`	402	Out of balance. See Balance & usage, or ask an admin to grant test credit.

Rate-limit errors

Code	HTTP	Meaning & fix
`RATE_LIMITED`	429	Rate limited by requests per minute, tokens per minute, or search frequency. Retrying later only helps for burst limits: a single large request can exceed the per-minute token limit on its own — a video sent to the embeddings API is base64 (~929 tokens per KB), so a 300 KB clip is ~279,000 tokens. In that case use a key on a plan with a higher tpm (video embedding effectively needs Pro or above) rather than retrying.
`parallel_limit_exceeded`	429	Too many concurrent requests. Reduce requests in flight.

File upload errors

Code	HTTP	Meaning & fix
`FILE_TOO_LARGE`	400	File exceeds the 50 MB per-file limit. Note that native media (image / audio / video) sent inline has a lower 15 MB ceiling, and a direct API request body must stay under 25 MB.
`FILE_EMPTY`	400	No extractable text (e.g. scanned PDF / image with no text). Use a text-based file.
`FILE_TEXT_DECODE_FAILED`	400	File is corrupted or can't be parsed (e.g. encrypted PDF). Check the file and retry.
`QUERY_BLOCKED`	403	A suspected secret (private key, token, etc.) was detected in the input and blocked. Remove sensitive content.

Upstream / provider errors

Code	HTTP	Meaning & fix
`PROVIDER_UNAVAILABLE`	503	The upstream provider is temporarily unavailable. Retry later; if it persists, contact an admin.

Still stuck?

Model issues: make sure model is a valid model ID
Permission issues: see Permissions & model scope
Balance issues: see Balance & usage
Configuration issues: see OpenAI-compatible tools