Because Claude requests on Vertex AI go to Google's endpoints, failures come back as Google Cloud status codes — PERMISSION_DENIED, RESOURCE_EXHAUSTED, INVALID_ARGUMENT, FAILED_PRECONDITION — rather than Anthropic-style errors. The code tells you which layer failed: identity, quota, request shape, or project setup. This reference maps each to its usual root causes, drawn from Google's and Anthropic's documentation for Claude on Vertex.
PERMISSION_DENIED (403): identity and enablement
The caller reached Vertex but wasn't allowed in. Check, in order:
Missing IAM role. Making prompt requests requires the aiplatform.endpoints.predict permission, included in the Vertex AI User role (roles/aiplatform.user). Grant it with gcloud projects add-iam-policy-binding to the exact principal your code runs as — a frequent trap is granting the developer's user account while production runs as a service account.
Model not enabled. Each Claude model must be enabled from its Model Garden card before use, which requires the Consumer Procurement Entitlement Manager role (roles/consumerprocurement.entitlementManager). Enablement is per-project: a model enabled in staging is not enabled in prod.
Org policy or perimeter in the way. Partner-model enablement needs the Cloud Commerce Consumer Procurement API allowed by org policy; separately, admins can block the global endpoint with the constraints/gcp.restrictEndpointUsage constraint, and a VPC Service Controls perimeter blocks public access to Vertex unless callers are allowlisted. If a request works from one network or region setting and not another, suspect these. See the dedicated 403 diagnosis guide for a step-by-step decision tree, and remember stale local credentials are cheaply eliminated by re-running gcloud auth application-default login.
RESOURCE_EXHAUSTED (429): quota
You're sending more than your project's quota allows. Useful specifics from Google's Claude quota documentation: models launched after May 26, 2026 draw from shared lineage quotas — all Opus versions share one anthropic-claude-opus bucket per location — so a burst on Opus 4.7 can 429 your Opus 4.8 traffic. Older models have per-model QPM (queries per minute) and TPM (tokens per minute) quotas instead. Two structural remedies before you write code: global-endpoint quota and each multi-region-endpoint quota are independent buckets, so splitting workloads across endpoint types adds headroom; and increases are requested on the console's Quotas & System Limits page. In code, exponential backoff plus a client-side rate limiter is the standard treatment — detailed in handling 429 RESOURCE_EXHAUSTED. One diagnostic caveat: the console quota page's token usage display can be inaccurate (Anthropic's estimation/refund system); trust the token_count metrics in Metrics Explorer.
INVALID_ARGUMENT (400): request shape
The request reached the model family but was malformed. The Vertex-specific causes first:
| Cause | Fix |
|---|---|
Wrong or missing anthropic_version | Body field (not header), exactly "vertex-2023-10-16" |
model placed in the request body | Model goes in the endpoint URL on Vertex; use the SDK to avoid this class entirely |
| Role sequence invalid | Messages must alternate user/assistant and start with user |
| Thinking budget out of range | budget_tokens must be ≥ 1024 and < max_tokens (extended thinking, supported models) |
| Payload too large | 30 MB request cap; 5 MB per image, max 100 images |
Model-behavior 400s come next: newer models reject parameters older ones accepted. For example, per Anthropic's migration guidance, Opus 4.8 and Sonnet 5 return 400 for manual extended thinking, non-default temperature/top_p/top_k, and assistant prefill. If an error appeared right after a model upgrade, diff your parameters against the migration guide before blaming Vertex.
FAILED_PRECONDITION: project state
The request was fine; the project isn't ready. Usual suspects: billing not enabled on the project; the Vertex AI API (aiplatform.googleapis.com) not enabled (fixing that requires roles/serviceusage.serviceUsageAdmin); or the model's Terms of Service not accepted. On that last one, Google documents a hard case: if your billing account is managed by a reseller Anthropic prohibits, you will be unable to accept the terms or enable Claude models at all — a procurement conversation, not an engineering fix.
Where to go next
Run the project preflight checklist to prevent most of these before the first call, and see retries and fallbacks for making the errors you can't prevent survivable.