En esta página, se describen los códigos de error de Spanner y las acciones recomendadas para manejarlos. Las APIs de Google, incluido Spanner, usan los códigos de error canónicos definidos por google.rpc.Code.
Cuando una solicitud de Spanner se realiza correctamente, la API muestra un código de estado HTTP 200 OK junto con los datos solicitados en el cuerpo de la respuesta.
Cuando una solicitud falla, la API de Spanner muestra un código de estado HTTP 4xx o 5xx que identifica de forma genérica la falla y una respuesta que proporciona información más específica sobre los errores que la causaron.
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 detallan 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: Vuelve a intentar la solicitud o estructura tus entidades para 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 para reducir la contención. |
ALREADY_EXISTS |
Ya existe la entidad que un cliente intentó crear (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 momento real en el que una respuesta es útil. Ten en cuenta que, en el caso de 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 Soluciona problemas de errores de vencimiento excedido. |
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 consultar desde una marca de tiempo que superó la inactividad máxima de la marca de tiempo. | No vuelvas a intentarlo sin solucionar el problema. |
INTERNAL |
El servidor mostró un error. Algunas invariables que espera el sistema subyacente están rotas. | 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 actualizar una entidad o consultar 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ó algún recurso. En el caso del plano de administrador, es posible que el proyecto haya excedido su cuota o que se haya agotado el espacio de todo el sistema de archivos. En el caso del plano de datos, esto puede suceder si tus nodos de Spanner están sobrecargados. |
En el plano de administrador, verifica que no hayas excedido la cuota de Spanner o del proyecto. Si superaste una cuota, solicita un aumento de cuota o espera a que se restablezca antes de volver a intentarlo. Configura los reintentos para que usen la retirada exponencial. Para el plano de datos, verifica que tus nodos de Spanner no hayan excedido su capacidad. Spanner vuelve a intentar estos errores en la biblioteca cliente. Si todos los reintentos fallan, consulta Errores del mecanismo de control de flujo. En general, si tu aplicación experimenta errores RESOURCE_EXHAUSTED, trata la situación como un error UNAVAILABLE y vuelve a intentarlo con una 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. | Verifica que tu solicitud sea segura. Luego, vuelve a intentarlo con una retirada exponencial. |
Errores del mecanismo de control de flujo
Spanner puede activar su mecanismo de control de flujo para protegerse contra la sobrecarga en las siguientes condiciones:
- Hay un uso alto de la CPU en el nodo de Spanner. Si sospechas que tu solicitud está causando un uso elevado de la CPU, puedes usar las métricas de uso de CPU para investigar el problema.
- Puede haber hotspots, que aumentan el tiempo de procesamiento de la solicitud. Si sospechas que tu solicitud está causando hotspots, consulta Cómo encontrar hotspots en tu base de datos para investigar el problema. Para obtener más información, consulta Visualizador de claves.
El mecanismo de control de flujo es compatible con las siguientes bibliotecas cliente:
El tiempo general para que se complete la solicitud no aumentará debido al uso del mecanismo de control de flujo. Sin este mecanismo, Spanner espera
antes de procesar la solicitud y, finalmente, muestra un error DEADLINE_EXCEEDED.
Cuando el mecanismo de control de flujo está activo, Spanner envía las solicitudes al cliente para que las vuelva a intentar. Si el reintento consume toda la fecha límite proporcionada por el usuario, el cliente recibe un error RESOURCE_EXHAUSTED.
Se muestra este error si Spanner estima que el tiempo de procesamiento de la solicitud es demasiado largo. El error propaga el control de flujo y Spanner vuelve a intentar la solicitud al cliente, en lugar de acumular reintentos de forma interna. Esto permite que Spanner evite acumular consumo de recursos adicional.