HTTP status and error codes for JSON

The following document provides reference information about the status codes and error messages that are used in the Cloud Storage JSON API. For the page specific to the Cloud Storage XML API, see HTTP status and error codes for XML.

Error Response Format

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 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."
 }
}

The following table describes the elements that can appear in the response body of an 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. Example values include: `global` and `push`.
errors.`location`	The specific item within 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`.