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 la de Spanner, usan los códigos de error canónicos definidos por google.rpc.Code.

Cuando una solicitud de Spanner se realiza correctamente, la API devuelve 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 devuelve un código de estado HTTP 4xx o 5xx que identifica de forma genérica la falla, así como 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:
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 Ya existe la entidad que intentó crear un cliente (por ejemplo, insertar una fila con una clave primaria existente). No vuelvas a intentarlo sin solucionar el problema.
CANCELLED La operación se canceló (en 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 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 superó la máxima marca de tiempo de inactividad. No vuelvas a intentarlo sin solucionar el problema.
INTERNAL El servidor mostró un error. Algunas invariantes que el sistema subyacente espera 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 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 Se intentó realizar la operación 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 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 plano de datos, esto puede ocurrir si tus nodos de Spanner están sobrecargados.

Para obtener más información, consulta también los códigos de error relacionados con la sesión.		 En el plano del administrador, verifica que no hayas superado la cuota de Spanner o del proyecto. Si excediste una cuota, solicita un aumento o espera a que se restablezca antes de volver a intentarlo. Configura tus reintentos para que usen la 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 de RESOURCE_EXHAUSTED, trata la situación como un error de 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 que no son 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 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.

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 se produce 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 al grupo de sesiones y quita la sesión borrada del grupo.

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

    • Borra una sesión si permanece inactiva durante más de una hora. Esto puede ocurrir en trabajos de transmisión de datos en los que el procesamiento posterior 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 te encuentras con este error, verifica que tu código no borre sesiones de forma explícita, por ejemplo, cerrando el cliente de la 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 errores RESOURCE_EXHAUSTED: No session available in the pool o RESOURCE_EXHAUSTED: Timed out after waiting X ms for acquiring session 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 podrían 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 de sesiones configurada. 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 del 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 el parámetro de configuración de tiempo de espera para adquirir la sesión, las solicitudes nuevas no podrán obtener una sesión del grupo de sesiones. Investiga por qué tus solicitudes tardan tanto en completarse. Optimiza tus consultas o la lógica de la aplicación para reducir el tiempo de ejecución. Puedes aumentar el parámetro de configuración del tiempo de espera para adquirir la sesión. También puedes habilitar sesiones multiplexadas para las bibliotecas cliente aptas y, así, mejorar el uso de las sesiones.
Hay filtraciones de sesiones. Se produce una pérdida de sesión cuando tu aplicación extrae una sesión del grupo, pero no la devuelve después de completar la solicitud. Esto suele ocurrir cuando los iteradores o los conjuntos de resultados no se cierran correctamente en el código. Si se filtran todas las sesiones, no habrá sesiones disponibles para las solicitudes nuevas. Depura el código de tu aplicación para identificar y corregir las filtraciones 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 filtraciones de sesiones. También puedes usar la función de limpieza automática de fugas de sesiones para configurar tu grupo de sesiones de modo que resuelva automáticamente las transacciones inactivas.
La creación de sesiones es lenta. La creación de sesiones es una operación costosa a nivel de procesamiento. Las bibliotecas cliente envían APIs de BatchCreateSessions para crear sesiones iniciales (según la configuración de minSession) y APIs de CreateSessions para sesiones adicionales (hasta maxSession). Si la creación de sesiones tarda más que el parámetro de configuración de tiempo de espera de adquisición de sesiones, es posible que se agote el tiempo de espera de las solicitudes nuevas mientras se espera a las sesiones. Verifica la latencia de las llamadas a las APIs de BatchCreateSessions y CreateSessions. La creación lenta de sesiones puede deberse a problemas de recursos en 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 alto de CPU en el nodo de Spanner. Si sospechas que tu solicitud está causando un uso de CPU elevado, puedes usar las métricas de uso de CPU para investigar el problema.
  • Es posible que haya puntos de acceso que aumenten el tiempo de procesamiento de la solicitud. Si sospechas que tu solicitud está causando puntos críticos, consulta Cómo encontrar puntos críticos 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, devuelve un error DEADLINE_EXCEEDED.

Cuando el mecanismo de control de flujo está activo, Spanner envía las solicitudes de vuelta al cliente para que las reintente. 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.