Códigos de error y manejo de errores de Spanner

En esta página, se describen los códigos de error de Spanner y las acciones recomendadas para para manejar estos errores. Las APIs de Google, incluida Spanner, usan la códigos de error canónicos definidos por google.rpc.Code.

Cuando una solicitud de Spanner se realiza de forma correcta, la API devuelve un 200 OK junto con los datos solicitados en el cuerpo de la respuesta.

Cuando falla una solicitud, la API de Spanner muestra un Código de estado 4xx o 5xx que identifica genéricamente la falla, así como un respuesta que proporciona información más específica sobre los errores que causaron de la falla.

El objeto de respuesta contiene un solo campo error cuyo valor contiene los siguientes elementos:

Elemento Descripción
code Un código de estado HTTP que identifica genéricamente la falla de la solicitud.
message Información específica sobre la falla de la solicitud.
status El código de error canónico (google.rpc.Code) para las API de Google. Los códigos que la API de Spanner puede mostrar se enumeran en Códigos de error.

Si una solicitud realizada con un tipo de contenido de application/x-protobuf genera un error, se mostrará un mensaje google.rpc.Status en serie como la carga útil.

Códigos de error

La forma recomendada de clasificar los errores es inspeccionar el valor del código de error canónico (google.rpc.Code). En los errores de JSON, este código aparece en el campo status. En los errores application/x-protobuf, está en el campo code.

Código de error Descripción Acción recomendada
ABORTED La operación se anuló, por lo general debido a un problema de simultaneidad, como una falla en la verificación del secuenciador o la anulación de la transacción. Indica que la solicitud entró en conflicto con otra. Para una confirmación no transaccional:
Reintenta la solicitud o estructura tus entidades a fin de reducir la contención.

Para solicitudes que forman parte de una confirmación transaccional:
Vuelve a intentar la transacción completa o estructura tus entidades a fin de reducir la contención.
ALREADY_EXISTS La entidad que un cliente intentó crear ya existe (por ejemplo, insertar una fila con una clave primaria existente). No vuelvas a intentarlo sin solucionar el problema.
CANCELLED La operación se canceló (por lo general, la cancela el emisor). Vuelve a intentar la operación.
DEADLINE_EXCEEDED El plazo venció antes de que la operación se pudiera completar. Investiga si el plazo es suficiente. Usa una fecha límite que corresponda al tiempo real en el que la respuesta es útil. Ten en cuenta que para las operaciones que cambian el estado del sistema, es posible que se muestre un error incluso si la operación se completó correctamente.

Para obtener sugerencias, consulta Cómo solucionar errores relacionados con la fecha límite excedida.
FAILED_PRECONDITION La operación se rechazó porque no se cumplió una condición previa para la solicitud. El campo de mensaje en la respuesta de error proporciona información sobre la condición previa que falló. Por ejemplo, leer o realizar consultas de una marca de tiempo que superó el máximo de obsolescencia de marca de tiempo. No vuelvas a intentarlo sin solucionar el problema.
INTERNAL El servidor mostró un error. Algunas variantes que espera el sistema subyacente están dañadas. No vuelvas a intentarlo a menos que comprendas la circunstancia y la causa específicas del error.
INVALID_ARGUMENT El cliente especificó un valor no válido. El campo de mensaje en la respuesta de error proporciona información sobre el valor que no fue válido. No vuelvas a intentarlo sin solucionar el problema.
NOT_FOUND Indica que no existe alguna entidad solicitada, como la actualización de una entidad o la consulta de una tabla o columna. No vuelvas a intentarlo sin solucionar el problema.
OUT_OF_RANGE La operación se intentó fuera del rango válido. No vuelvas a intentarlo sin solucionar el problema.
PERMISSION_DENIED El usuario no tenía autorización para realizar la solicitud. No vuelvas a intentarlo sin solucionar el problema.
RESOURCE_EXHAUSTED Se agotó un recurso. Es posible que el proyecto haya superado su cuota o que se haya quedado sin espacio todo el sistema de archivos. Verifica que no superaste la cuota de Spanner o del proyecto. Si superaste la cuota, no lo intentes de nuevo sin solucionar el problema.

De lo contrario, vuelve a intentarlo con la retirada exponencial.
UNAUTHENTICATED La solicitud no tiene credenciales de autenticación válidas para la operación. No vuelvas a intentarlo sin solucionar el problema.
UNAVAILABLE El servidor no está disponible. Vuelve a intentarlo con una retirada exponencial. Ten en cuenta que no siempre es seguro reintentar operaciones no idempotentes.
UNIMPLEMENTED La operación no se implementó, no se admite o no está habilitada en este servicio. No vuelvas a intentarlo sin solucionar el problema.
UNKNOWN El servidor mostró un error desconocido. Los errores generados por APIs que no muestran suficiente información sobre el error pueden convertirse en este error. Comprueba que tu solicitud sea segura. Luego, vuelve a intentarlo con una retirada exponencial.