This page describes Spanner error codes and recommended actions to
handle these errors. Google APIs, including Spanner, use the
canonical error codes defined by google.rpc.Code.
When a Spanner request is successful, the API returns an HTTP
200 OK status code along with the requested data in the body of the response.
When a request fails, the Spanner API returns 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 response object contains a single field error whose value contains the
following elements:
| Element | Description |
|---|---|
code |
An HTTP status code that generically identifies the request failure. |
message |
Specific information about the request failure. |
status |
The canonical error code (google.rpc.Code) for Google APIs. Codes that may be returned by the Spanner API are listed in Error Codes. |
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 to 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.
| Error code | Description | Recommended action |
|---|---|---|
ABORTED |
The operation was aborted, typically due to concurrency issue such as a sequencer check failure or transaction abort. 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 |
The entity that a client attempted to create already exists (for example, inserting a row with an existing primary key). | Do not retry without fixing the problem. |
CANCELLED |
The operation was cancelled, typically by the caller. | Retry the operation. |
DEADLINE_EXCEEDED |
The deadline expired before the operation could complete. | Investigate if the deadline is sufficient. Use a deadline corresponding to the actual time in which a response is useful. Note that for operations that change the state of the system, an error might be returned even if the operation has completed successfully. For tips, see Troubleshoot deadline exceeded errors. |
FAILED_PRECONDITION |
The operation was rejected because 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 |
The server returned an error. Some invariants expected by the underlying system have been broken. | Do not retry unless you understand the specific circumstance and cause of the error. |
INVALID_ARGUMENT |
The client specified 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 some requested entity, such as updating an entity or querying a table or column, does not exist. | Do not retry without fixing the problem. |
OUT_OF_RANGE |
The operation was attempted past the valid range. | Do not retry without fixing the problem. |
PERMISSION_DENIED |
The user was not authorized to make the request. | Do not retry without fixing the problem. |
RESOURCE_EXHAUSTED |
Some resource has been exhausted. Perhaps the project exceeded its quota or the entire file system is out of space. | Verify that you did not exceed your Spanner or project quota. If you exceeded a quota, do not retry without fixing the problem. Otherwise, retry with exponential backoff. |
UNAUTHENTICATED |
The request does not have valid authentication credentials for the operation. | Do not retry without fixing the problem. |
UNAVAILABLE |
The server is currently unavailable | Retry using exponential backoff. Note that it is not always safe to retry non-idempotent operations. |
UNIMPLEMENTED |
The operation is not implemented or is not supported/enabled in this service. | Do not retry without fixing the problem. |
UNKNOWN |
Server returned an unknown error. Errors raised by APIs that do not return enough error information may be converted to this error. | Check that your request is safe. Then, retry with exponential backoff. |