Stay organized with collections
Save and categorize content based on your preferences.
When a Firestore in Datastore mode request is successful, the API will return an HTTP
200 OK status code along with the requested data in the body of the response.
When a request fails, the Datastore API will return an HTTP
4xx or 5xx status code that generically identifies the failure as well as a
response that provides more specific information about the error(s) that caused
the failure.
The rest of this page describes the structure of an error, enumerates specific
error codes, and recommends how to handle them.
The following is the structure of an error response for a JSON request:
If a request made with a content type of application/x-protobuf results in an
error, it will return a serialized google.rpc.Status message as the
payload.
Error Codes
The recommended way to classify errors is inspect the value of the
canonical error code (google.rpc.Code). In JSON errors, this code appears
in the status field. In application/x-protobuf errors, it's in the code
field.
Canonical Error Code
Description
Recommended Action
ABORTED
Indicates that the request conflicted with another request.
For a non-transactional commit: Retry the request or structure your entities to reduce contention.
For requests that are part of a transactional commit: Retry the entire transaction or structure your entities to reduce contention.
ALREADY_EXISTS
Indicates that the request attempted to insert an entity that already exists.
Do not retry without fixing the problem.
DEADLINE_EXCEEDED
A deadline was exceeded on the server.
Retry using exponential backoff.
FAILED_PRECONDITION
Indicates that a precondition for the request was not met. The message field in the error response provides information about the precondition that failed. One possible cause is running a query that requires an index not yet defined.
Do not retry without fixing the problem.
INTERNAL
Server returned an error.
Do not retry this request more than once.
INVALID_ARGUMENT
Indicates that a request parameter has an invalid value. The message field in the error response provides information as to which value was invalid.
Do not retry without fixing the problem.
NOT_FOUND
Indicates that the request attempted to update an entity that does not exist.
Do not retry without fixing the problem.
PERMISSION_DENIED
Indicates that the user was not authorized to make the request.
Do not retry without fixing the problem.
RESOURCE_EXHAUSTED
Indicates that the project exceeded either its quota or the region/multi-region capacity.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-09-03 UTC."],[[["\u003cp\u003eSuccessful Firestore in Datastore mode requests return an HTTP \u003ccode\u003e200 OK\u003c/code\u003e status code with the requested data.\u003c/p\u003e\n"],["\u003cp\u003eFailed requests return an HTTP \u003ccode\u003e4xx\u003c/code\u003e or \u003ccode\u003e5xx\u003c/code\u003e status code and an error response containing \u003ccode\u003ecode\u003c/code\u003e, \u003ccode\u003emessage\u003c/code\u003e, and \u003ccode\u003estatus\u003c/code\u003e fields.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003estatus\u003c/code\u003e field within error responses represents the canonical error code, crucial for classifying and understanding the nature of the error.\u003c/p\u003e\n"],["\u003cp\u003eThe content type of the request (\u003ccode\u003eapplication/x-protobuf\u003c/code\u003e or JSON) will determine the structure of the error in response, with the \u003ccode\u003ecode\u003c/code\u003e field being different depending on the content.\u003c/p\u003e\n"],["\u003cp\u003eSpecific error codes, such as \u003ccode\u003eABORTED\u003c/code\u003e, \u003ccode\u003eALREADY_EXISTS\u003c/code\u003e, or \u003ccode\u003eDEADLINE_EXCEEDED\u003c/code\u003e, provide detailed reasons for failure and guide appropriate actions like retrying or fixing the request.\u003c/p\u003e\n"]]],[],null,["# Errors and Error Handling\n\nWhen a Firestore in Datastore mode request is successful, the API will return an HTTP\n`200 OK` status code along with the requested data in the body of the response.\n| **Note:** The errors and status codes described in this page are returned by the low-level Datastore API. Note that client libraries may or may not return these same values.\n\nWhen a request fails, the Datastore API will return an HTTP\n`4xx` or `5xx` status code that generically identifies the failure as well as a\nresponse that provides more specific information about the error(s) that caused\nthe failure.\n\nThe rest of this page describes the structure of an error, enumerates specific\nerror codes, and recommends how to handle them.\n\nThe following is the structure of an error response for a JSON request: \n\n {\n \"error\": {\n \"code\": \"integer\",\n \"message\": \"string\",\n \"status\": \"string\"\n }\n }\n\nThe response object contains a single field `error` whose value contains the\nfollowing elements:\n\nHere's an example of an error response for a JSON request: \n\n {\n \"error\": {\n \"code\": 400,\n \"message\": \"Key path is incomplete: [Person: null]\",\n \"status\": \"INVALID_ARGUMENT\"\n }\n }\n\nIf a request made with a content type of `application/x-protobuf` results in an\nerror, it will return a serialized [`google.rpc.Status`](https://github.com/googleapis/googleapis/blob/master/google/rpc/status.proto) message as the\npayload.\n| **Note:** The text provided in the message could change at any time so applications should not depend on the actual text.\n\nError Codes\n-----------\n\nThe recommended way to classify errors is inspect the value of the\n[canonical error code](https://github.com/googleapis/googleapis/blob/master/google/rpc/code.proto) (`google.rpc.Code`). In JSON errors, this code appears\nin the `status` field. In `application/x-protobuf` errors, it's in the `code`\nfield."]]