Códigos de error de Spanner

En esta página se describen los códigos de error de Spanner y las acciones recomendadas para gestionarlos. 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 devuelve 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 devuelve un código de estado HTTP 4xx o 5xx que identifica de forma genérica el fallo, así como una respuesta que proporciona información más específica sobre los errores que han provocado el fallo.

El objeto de respuesta contiene un único campo error cuyo valor incluye los siguientes elementos:

Elemento Descripción
code Un código de estado HTTP que identifica de forma genérica el fallo de la solicitud.
message Información específica sobre el fallo de la solicitud.
status El código de error canónico (google.rpc.Code) de las APIs de Google. Los códigos que puede devolver la API de Spanner se indican en Códigos de error.

Si una solicitud realizada con el tipo de contenido application/x-protobuf genera un error, devolverá un mensaje google.rpc.Status serializado como 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 de application/x-protobuf, se encuentra en el campo code.

Código de error Descripción Acción recomendada
ABORTED La operación se ha cancelado, normalmente debido a un problema de simultaneidad, como un error de comprobación de secuenciador o una cancelación de transacción. Indica que la solicitud ha entrado en conflicto con otra. En el caso de una confirmación no transaccional:
vuelve a intentar la solicitud o estructura tus entidades para reducir la contención.

En el caso de las solicitudes que forman parte de una confirmación transaccional:
vuelve a intentar toda la transacción o estructura tus entidades para reducir la contención.
ALREADY_EXISTS La entidad que ha intentado crear un cliente ya existe (por ejemplo, insertar una fila con una clave principal que ya existe). No vuelvas a intentarlo sin solucionar el problema.
CANCELLED La operación se canceló. Normalmente, lo hizo la persona que llama. Vuelve a intentar la operación.
DEADLINE_EXCEEDED El tiempo de espera se ha agotado antes de que la operación se completara. Investiga si el plazo es suficiente. Usa una fecha límite que corresponda al momento 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 devuelva un error aunque la operación se haya completado correctamente.

Para obtener consejos, consulta Solucionar errores de tiempo de espera agotado.
FAILED_PRECONDITION La operación se ha rechazado porque no se ha cumplido una condición previa de la solicitud. El campo de mensaje de la respuesta de error proporciona información sobre la condición previa que no se ha cumplido. Por ejemplo, leer o consultar desde una marca de tiempo que haya superado la antigüedad máxima. No vuelvas a intentarlo sin solucionar el problema.
INTERNAL El servidor ha devuelto un error. Se han incumplido algunas invariantes que esperaba el sistema subyacente. No vuelvas a intentarlo a menos que conozcas las circunstancias específicas y la causa del error.
INVALID_ARGUMENT El cliente ha especificado un valor no válido. El campo de mensaje de la respuesta de error proporciona información sobre qué valor no era 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 una columna. No vuelvas a intentarlo sin solucionar el problema.
OUT_OF_RANGE Se intentó realizar la operación más allá del rango válido. No vuelvas a intentarlo sin solucionar el problema.
PERMISSION_DENIED El usuario no tenía autorización para hacer la solicitud. No vuelvas a intentarlo sin solucionar el problema.
RESOURCE_EXHAUSTED Se ha agotado algún recurso.

En el plano del administrador, es posible que el proyecto haya superado su cuota o que el sistema de archivos se haya quedado sin espacio.

En el plano de datos, esto puede ocurrir si los nodos de Spanner están sobrecargados.

Para obtener más información, consulta también los códigos de error relacionados con las sesiones.		 En el plano del administrador, comprueba que no hayas superado tu cuota de Spanner o de proyecto. Si has superado una cuota, solicita un aumento de la cuota o espera a que se restablezca antes de volver a intentarlo. Configura tus reintentos para que usen una retirada exponencial.

En el plano de datos, comprueba que tus nodos de Spanner no hayan superado su capacidad. Spanner vuelve a intentar solucionar estos errores en la biblioteca de cliente. Si fallan todos los reintentos, consulta la sección Errores del mecanismo de control de flujo.

En general, si tu aplicación experimenta errores RESOURCE_EXHAUSTED, trata la situación como si se tratara de un error UNAVAILABLE y vuelve a intentarlo con un retroceso exponencial.
UNAUTHENTICATED La solicitud no cuenta con 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 un tiempo de espera exponencial. Ten en cuenta que no siempre es seguro volver a intentar operaciones no idempotentes.
UNIMPLEMENTED La operación no se ha desplegado, no es compatible o no está habilitada en este servicio. No vuelvas a intentarlo sin solucionar el problema.
UNKNOWN El servidor ha devuelto un error desconocido. Los errores generados por APIs que no devuelven suficiente información de error pueden convertirse en este error. Comprueba que tu solicitud sea segura. A continuación, vuelve a intentarlo con un tiempo de espera exponencial.

Errores de sesión

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

Estos son algunos de los errores habituales relacionados con las sesiones que puede encontrar tu aplicación:

Sesión no encontrada

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

  • Es posible que tu aplicación cliente elimine una sesión de forma explícita. Por ejemplo, si cierras un cliente de base de datos en tu código o llamas directamente a la API deleteSessions, se eliminará la sesión. Si no usas una de las bibliotecas de cliente de Spanner, crea una sesión cuando se produzca este error. Añade la nueva sesión a tu grupo de sesiones y elimina la sesión eliminada del grupo.

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

    • Elimina 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 posterior tarda más que el tiempo de espera de inactividad de la sesión. Si usas una tarea de Dataflow, añade 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 elimina una sesión si tiene más de 28 días. Si usas la biblioteca de cliente, se encarga de estos casos automáticamente. Si no usas una de las bibliotecas de cliente de Spanner, crea una sesión cuando se produzca este error. Añade la nueva sesión a tu grupo de sesiones y elimina la sesión eliminada del grupo.

  • Si usas una de las bibliotecas de cliente de Spanner, la biblioteca gestiona las sesiones automáticamente. Si se produce este error, compruebe que su código no elimina 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 gestión de sesiones de la biblioteca de cliente.

Recurso agotado

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 ocurre cuando no hay sesiones disponibles para procesar nuevas solicitudes de lectura o escritura.

En la siguiente tabla se describen algunos motivos por los que se pueden producir 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 el número máximo de sesiones configurado. Todas las sesiones del grupo están ocupadas y no hay ninguna disponible para nuevas solicitudes. Habilita las sesiones multiplexadas. Las sesiones multiplexadas permiten que varias transacciones y lecturas compartan una sola sesión, lo que puede reducir el número total de sesiones que necesita tu aplicación. También puedes aumentar la configuración de maxSession o minSession en los ajustes 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 periodos prolongados. Si estas solicitudes tardan más que el tiempo de espera de adquisición de la sesión, las nuevas solicitudes no podrán 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 el tiempo de espera de adquisición de la sesión. También puedes habilitar sesiones multiplexadas en las bibliotecas de cliente aptas para mejorar el uso de las sesiones.
Hay fugas de sesiones. Se produce una fuga 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á ninguna disponible para las nuevas solicitudes. Depura el código de tu aplicación para identificar y corregir las fugas 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 para detectar fugas de sesiones. También puedes usar la función de limpieza automática de fugas de sesiones para configurar tu grupo de sesiones de forma que resuelva automáticamente las transacciones inactivas.
La creación de sesiones es lenta. Crear sesiones es una operación que requiere muchos recursos de computación. Las bibliotecas de cliente envían APIs BatchCreateSessions para crear sesiones iniciales (basadas en la configuración de minSession) y APIs CreateSessions para crear sesiones adicionales (hasta maxSession). Si la creación de sesiones tarda más que el tiempo de espera de adquisición de sesiones, es posible que se agote el tiempo de espera de las nuevas solicitudes mientras esperan las sesiones. Verifica la latencia de las llamadas a las APIs BatchCreateSessions y CreateSessions. La creación lenta de sesiones puede deberse a problemas de recursos en Spanner o a un gran número de operaciones de creación de sesiones simultáneas.

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:

  • El uso de CPU en el nodo de Spanner es elevado. Si sospecha que su solicitud está provocando un uso elevado de la CPU, puede usar las métricas de uso de la CPU para investigar el problema.
  • Puede haber puntos de acceso que aumenten el tiempo de procesamiento de la solicitud. Si sospechas que tu solicitud está provocando puntos de acceso, consulta Buscar 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 de cliente:

El tiempo total que tarda en completarse la solicitud no aumenta 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 vuelve a enviar solicitudes al cliente para que lo intente de nuevo. Si el reintento consume todo el plazo proporcionado por el usuario, el cliente recibe un error RESOURCE_EXHAUSTED. Este error se devuelve 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 enviar la solicitud al cliente, en lugar de acumular reintentos internamente. De esta forma, Spanner evita acumular consumo de recursos adicional.