Errors

A failed request returns an error code and a message. Over HTTP, the body is JSON and the HTTP status matches the code:

{
  "code": "invalid_argument",
  "message": "validation error: project_id: must be a valid project ID (e.g. proj-01kmyy3t719crcnrrvk1mgyjd0)"
}

Over gRPC, the same code comes back as the gRPC status, such as InvalidArgument.

Codes

Code	HTTP status	Meaning
invalid_argument	400	A field is missing or invalid. The message names the field.
failed_precondition	400	The resource does not allow this right now, such as deleting a protected zone or a bucket that is not empty.
unauthenticated	401	The token is missing, invalid, or expired.
permission_denied	403	The token has no access to the project or method.
not_found	404	The resource does not exist.
already_exists	409	A resource with that name already exists.
resource_exhausted	429	A quota or rate limit is reached.
unimplemented	501	The method is not available yet.
internal	500	Something failed on our side.

Good to know

• Validation stops at the first invalid field. Fix it and send the request again to see the next one.
• Messages for not_found, already_exists, and permission_denied are always generic, such as resource not found.
• Only internal and rate limit exceeded (resource_exhausted with a Retry-After header) are worth retrying without changing the request. Quota errors need a free slot or a quota increase.