Error Codes Reference

✅ Fresh -- Updated March 2026 from official Google Cloud documentation.

Complete error code table with gRPC codes, HTTP status codes, descriptions, and recommended actions.

Error Code Table

gRPC Code	HTTP	Status	Retryable	Description	Action
0	200	OK	N/A	Success	None needed
1	499	CANCELLED	No	Client cancelled the request	Check client-side timeout settings
2	500	UNKNOWN	Yes	Unknown server error	Retry with backoff; check logs
3	400	INVALID_ARGUMENT	No	Malformed request	Check request body, field types, required fields
4	504	DEADLINE_EXCEEDED	Yes	Request took too long	Increase timeout; reduce request scope
5	404	NOT_FOUND	No	Resource does not exist	Verify resource name and project
6	409	ALREADY_EXISTS	No	Resource already exists	Use a different ID or get existing resource
7	403	PERMISSION_DENIED	No	Insufficient permissions	Check IAM roles and API enablement
8	429	RESOURCE_EXHAUSTED	Yes	Rate limited or quota exceeded	Implement backoff; request quota increase
9	400	FAILED_PRECONDITION	No	System not in required state	Check preconditions (e.g., etag mismatch)
10	409	ABORTED	Yes	Concurrency conflict	Retry (read-modify-write pattern)
11	400	OUT_OF_RANGE	No	Value outside valid range	Check field value constraints
12	501	UNIMPLEMENTED	No	Method not supported	Check API version and service docs
13	500	INTERNAL	Yes	Internal server error	Retry with backoff
14	503	UNAVAILABLE	Yes	Service temporarily unavailable	Retry with backoff
15	500	DATA_LOSS	No	Unrecoverable data loss	Contact support immediately
16	401	UNAUTHENTICATED	No	Missing or invalid credentials	Check auth token, API key, or service account

Decision Diagram

Most Common Errors and Fixes

401 UNAUTHENTICATED

# Check if you have valid credentials
gcloud auth print-access-token

# Re-authenticate if expired
gcloud auth login
gcloud auth application-default login

403 PERMISSION_DENIED

# Check what roles your account has
gcloud projects get-iam-policy PROJECT_ID \
  --flatten="bindings[].members" \
  --filter="bindings.members:USER_EMAIL"

# Check if the API is enabled
gcloud services list --enabled | grep SERVICE_NAME

# Grant a role
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="user:USER_EMAIL" \
  --role="roles/storage.objectViewer"

429 RESOURCE_EXHAUSTED

# Check current quota usage in Console
# https://console.cloud.google.com/iam-admin/quotas

# Request a quota increase via Console or:
gcloud alpha services quota update \
  --service=SERVICE_NAME \
  --consumer=projects/PROJECT_ID \
  --metric=METRIC_NAME \
  --unit=1/min/{project} \
  --value=NEW_LIMIT

404 NOT_FOUND

# Verify the resource exists
gcloud RESOURCE_TYPE list --project=PROJECT_ID

# Check you're using the correct project
gcloud config get-value project

# Verify the full resource name format
# Correct: projects/my-project/topics/my-topic
# Incorrect: my-topic

Retry Matrix

Error	Retry?	Strategy
400 INVALID_ARGUMENT	No	Fix request
401 UNAUTHENTICATED	No	Fix credentials
403 PERMISSION_DENIED	No	Fix IAM/enablement
404 NOT_FOUND	No	Fix resource name
409 ALREADY_EXISTS	No	Use existing or different ID
409 ABORTED	Yes	Retry immediately
429 RESOURCE_EXHAUSTED	Yes	Exponential backoff
500 INTERNAL	Yes	Exponential backoff
503 UNAVAILABLE	Yes	Exponential backoff
504 DEADLINE_EXCEEDED	Yes	Increase timeout + retry

See Also

• Error Handling Design -- Error model architecture
• Troubleshooting -- Common issue resolutions
• Authentication SOP -- Fix 401/403 errors