HTTP Status and Error Codes

The following document provides reference information about the status codes and error messages that are used in the Google Cloud Storage JSON API.

Error Response Format

Google Cloud Storage uses the standard HTTP error reporting format for the JSON API. Successful requests return HTTP status codes in the 2xx range. Failed requests return status codes in the 4xx and 5xx ranges. Requests that require a redirect returns status codes in the 3xx range. Error responses usually include a JSON document in the response body, which contains information about the error.

The following examples show some common errors. Note that the header information in the responses is omitted.

`401 Unauthorized`

The following is an example of an error response you receive if you try to list list the buckets for a project but do not provide an authorization header.

401 Unauthorized

{
"error": {
 "errors": [
  {
   "domain": "global",
   "reason": "required",
   "message": "Login Required",
   "locationType": "header",
   "location": "Authorization"
  }
 ],
 "code": 401,
 "message": "Login Required"
 }
}

`403 Forbidden`

This is an example of an error response you receive if you try to list the buckets of a non-existent project or one in which you don't have permission to list buckets.

403 Forbidden

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "forbidden",
    "message": "Forbidden"
    }
  ],
  "code": 403,
  "message": "Forbidden"
 }
}

`404 Not Found`

The following is an example of an error response you receive if you try to retrieve an object that does not exist.

404 Not Found

{
"error": {
 "errors": [
  {
   "domain": "global",
   "reason": "notFound",
   "message": "Not Found"
  }
 ],
 "code": 404,
 "message": "Not Found"
 }
}

`409 Conflict`

The following is an example of an error response you receive if you try to create a bucket using the name of a bucket you already own.

409 Conflict

{
"error": {
 "errors": [
  {
   "domain": "global",
   "reason": "conflict",
   "message": "You already own this bucket. Please select another name."
  }
 ],
 "code": 409,
 "message": "You already own this bucket. Please select another name."
 }
}

`412 Precondition Failed`

The following is an example of an error response you receive if you try to get an object and specify a precondition (e.g., ifGenerationMatch ) that fails.

412 Precondition Failed
{
"error": {
 "errors": [
  {
   "domain": "global",
   "reason": "conditionNotMet",
   "message": "Precondition Failed",
   "locationType": "header",
   "location": "If-Match"
  }
 ],
 "code": 412,
 "message": "Precondition Failed"
 }
}

The following table describes the elements can appear in the response body of error. Fields should be used together to help determine the problem. Also, the example values given below are meant for illustration and are not an exhaustive list of all possible values.

Element	Description
`code`	An HTTP status code value, without the textual description. Example values include: `400 Bad Request` , `401 Unauthorized` , and `404 Not Found` .
`error`	A container for the error information.
`errors`	A container for the error details.
errors. `domain`	The scope of the error. Always returns `global` .
errors. `location`	The specific item withing the `locationType` that caused the error. For example, if you specify an invalid value for a parameter, the `location` will be the name of the parameter. Example values include: `Authorization` , `project` , and `projection` .
errors. `locationType`	The location or part of the request that caused the error. Use with `location` to pinpoint the error. For example, if you specify an invalid value for a parameter, the `locationType` will be `parameter` and the `location` will be the name of the parameter. Example values include `header` and `parameter` .
errors. `message`	Description of the error. Example values include `Invalid argument` , `Login required` , and `Required parameter: project` .
errors. `reason`	Example values include `invalid` , `invalidParameter` , and `required` .
`message`	Description of the error. Same as errors. `message` .