Códigos de error de Spanner

En esta página, se describen los códigos de error de Spanner y las acciones recomendadas para controlarlos. Las APIs de Google, incluida 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 falla una solicitud, la API de Spanner muestra un código de estado HTTP 4xx o 5xx que identifica genéricamente la falla, así como una respuesta que proporciona información más específica sobre los errores que causaron 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 muestra la API de Spanner se describen en la sección 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 code campo.

Código de error Descripción Acción recomendada
ABORTED La operación se anuló. Esto suele ocurrir 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 solicitud.

Para obtener más información sobre los errores Database schema has changed, consulta Error Database schema has changed.		 Para una confirmación no transaccional:
Reintenta 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 intentó crear un cliente (por ejemplo, insertar una fila con una clave primaria existente). No vuelvas a intentar la operación 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 un plazo que corresponda al tiempo 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 probable que se muestre un error incluso si la operación se completó correctamente.

Para obtener sugerencias, consulta Soluciona problemas de errores de plazo 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 excedió la máxima marca de tiempo de inactividad. No vuelvas a intentar la operación sin solucionar el problema.
INTERNAL El servidor mostró un error. Algunos invariantes que espera el sistema subyacente están rotos. 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 intentar la operación 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 intentar la operación sin solucionar el problema.
OUT_OF_RANGE La operación se intentó fuera del rango válido. No vuelvas a intentar la operación sin solucionar el problema.
PERMISSION_DENIED El usuario no tenía autorización para hacer la solicitud. No vuelvas a intentar la operación sin solucionar el problema.
RESOURCE_EXHAUSTED Algunos recursos se agotaron.

En el caso del plano del 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.

Para obtener más información, consulta también Códigos de error relacionados con la sesión.		 En el caso del plano del administrador, verifica que no hayas excedido tu cuota de Spanner o del proyecto. Si excediste una cuota, solicita un aumento de cuota o espera a que se restablezca antes de volver a intentarlo. Configura tus reintentos para usar una retirada exponencial.

En el caso del 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 fallan todos los reintentos, 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 intentar la operación 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 intentar la operación sin solucionar el problema.
UNKNOWN El servidor mostró un error desconocido. Los errores que las APIs generan y que no muestran suficiente información pueden convertirse en este error. Verifica que tu solicitud sea segura. Luego, vuelve a intentarlo con una retirada exponencial.

Error Database schema has changed

Es posible que veas un error ABORTED con un mensaje similar a uno de los siguientes:

  • Database schema has changed
  • Transaction aborted. Database schema probably changed during transaction, retry may succeed.

Por lo general, estos errores ocurren cuando una actualización del esquema anula la transacción. Sin embargo, otros motivos también pueden activarlos sin una actualización explícita del esquema. Por ejemplo, un estado interno temporal, como un esquema de cliente obsoleto durante una confirmación de transacción, puede activar este error.

Al igual que otros errores ABORTED, controla este error volviendo a intentar la transacción completa.

Errores de sesión

Spanner usa sesiones para administrar las interacciones entre tu aplicación y la base de datos. Las sesiones representan una conexión a la base de datos y facilitan operaciones como lecturas y escrituras.

Entre los errores comunes relacionados con la sesión que puede encontrar tu aplicación, se incluyen los siguientes:

No se encontró la sesión

El error Session not found ocurre cuando tu aplicación intenta usar una sesión que ya no existe. Esto puede suceder por varios motivos.

  • Es posible que tu aplicación cliente borre una sesión de forma explícita. Por ejemplo, cerrar un cliente de base de datos en tu código o llamar directamente a la API de deleteSessions quita la sesión. Si no usas una de las bibliotecas cliente de Spanner, crea una sesión nueva cuando se produzca este error. Agrega la sesión nueva a tu grupo de sesiones y quita la sesión borrada del grupo.

  • Spanner también borra sesiones automáticamente en ciertas condiciones.

    • Borra una sesión si permanece inactiva durante más de una hora. Esto puede ocurrir en trabajos de flujo de datos en los que el procesamiento de nivel inferior tarda más que el tiempo de espera de inactividad de la sesión. Si usas un trabajo de Dataflow, agrega una operación de transformación Reshuffle después de la lectura de Spanner en la canalización de Dataflow. Esto puede ayudar a desacoplar la operación de lectura de Spanner de los pasos de procesamiento posteriores de larga duración.

    • Spanner también borra una sesión si tiene más de 28 días. Si usas la biblioteca cliente, esta controla estos casos automáticamente. Si no usas una de las bibliotecas cliente de Spanner, crea una sesión nueva cuando se produzca este error. Agrega la sesión nueva a tu grupo de sesiones y quita la sesión borrada del grupo.

  • Si usas una de las bibliotecas cliente de Spanner, la biblioteca administra las sesiones automáticamente. Si encuentras este error, verifica que tu código no borre sesiones de forma explícita, por ejemplo, cerrando el cliente de base de datos. En ocasiones, esto también puede deberse a un problema en la administración de sesiones de la biblioteca cliente.

Se agotó el recurso

Los RESOURCE_EXHAUSTED: No session available in the pool o RESOURCE_EXHAUSTED: Timed out after waiting X ms for acquiring session errores indican que tu aplicación no puede adquirir una sesión del grupo de sesiones. Esto sucede cuando no hay sesiones disponibles para procesar solicitudes nuevas de lectura o escritura.

En la siguiente tabla, se describen algunos motivos que pueden causar estos errores y las acciones recomendadas correspondientes.

Motivo Acción recomendada
Todas las sesiones del grupo están en uso. Es posible que tu aplicación reciba más solicitudes simultáneas que la cantidad máxima configurada de sesiones. Todas las sesiones del grupo están ocupadas y no hay sesiones disponibles para solicitudes nuevas. Habilita las sesiones multiplexadas. Las sesiones multiplexadas permiten que varias transacciones y lecturas compartan una sola sesión, lo que puede reducir la cantidad total de sesiones que requiere tu aplicación. También puedes aumentar la configuración de maxSession o minSession en la configuración de tu grupo de sesiones.
Las solicitudes tardan mucho en completarse. Las solicitudes de lectura o escritura de larga duración pueden ocupar todas las sesiones disponibles durante períodos prolongados. Si estas solicitudes tardan más que la configuración del tiempo de espera de adquisición de la sesión, las solicitudes nuevas no pueden obtener una sesión del grupo de sesiones. Investiga por qué tus solicitudes tardan mucho en completarse. Optimiza tus consultas o la lógica de la aplicación para reducir el tiempo de ejecución. Puedes aumentar la configuración del tiempo de espera de adquisición de la sesión. También puedes habilitar sesiones multiplexadas para bibliotecas cliente aptas para mejorar el uso de la sesión.
Hay pérdidas de sesión. Se produce una pérdida de sesión cuando tu aplicación extrae una sesión del grupo, pero no la muestra después de completar la solicitud. Por lo general, esto sucede cuando los iteradores o los conjuntos de resultados no se cierran correctamente en tu código. Si se pierden todas las sesiones, no habrá sesiones disponibles para solicitudes nuevas. Depura el código de la aplicación para identificar y corregir las pérdidas de sesión. Asegúrate de que tu código cierre correctamente todos los iteradores y conjuntos de resultados. Para obtener más información, consulta Soluciones de detección de pérdidas de sesión. También puedes usar la función de limpieza automática de pérdidas de sesión para configurar tu grupo de sesiones para que resuelva automáticamente las transacciones inactivas.
La creación de sesiones es lenta. La creación de sesiones es una operación costosa desde el punto de vista computacional. Las bibliotecas cliente envían BatchCreateSessions APIs para crear sesiones iniciales (según la configuración de minSession) y CreateSessions APIs para sesiones adicionales (hasta maxSession). Si la creación de sesiones tarda más que la configuración del tiempo de espera de adquisición de la sesión, es posible que se agote el tiempo de espera de las solicitudes nuevas mientras esperan sesiones. Verifica la latencia de BatchCreateSessions y CreateSessions llamadas a la API. La creación lenta de sesiones puede deberse a problemas de recursos en el lado de Spanner o a una gran cantidad de operaciones simultáneas de creación de sesiones.

Errores del mecanismo de control de flujo

Spanner puede activar su mecanismo de control de flujo para protegerse de la sobrecarga en las siguientes condiciones:

  • Hay un uso elevado de CPU en el nodo de Spanner. Si sospechas que tu solicitud está causando un uso elevado de CPU, puedes usar las métricas de uso de CPU para investigar el problema.
  • Es posible que haya puntos de acceso, lo que aumenta el tiempo de procesamiento de la solicitud. Si sospechas que tu solicitud está causando puntos de acceso, consulta Cómo encontrar puntos de acceso en tu base de datos para investigar el problema. Para obtener más información, consulta Key Visualizer.

El mecanismo de control de flujo es compatible con las siguientes bibliotecas cliente:

El tiempo total 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 solicitudes al cliente para que vuelva a intentarlo. Si el reintento consume todo el plazo proporcionado 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 un consumo de recursos adicional.