En esta página, se describen los códigos de estado HTTP y los mensajes de error que devuelve la API de BigQuery. Puedes usar estos códigos para solucionar problemas y resolver fallas de solicitudes, y verificar el comportamiento de la API.
Para obtener más información sobre los errores que no son de la API, los errores de conectividad de la biblioteca cliente y los errores de la consola de Google Cloud , consulta Mensajes de error.
Para obtener más información sobre los errores de consulta, consulta Soluciona errores de consulta.
Para obtener más información sobre los errores de inserción de transmisión, consulta Soluciona problemas de inserción de transmisión.
Formato de respuesta de error
BigQuery usa el formato estándar de informes de errores de HTTP para su
API. Las solicitudes exitosas devuelven códigos de estado HTTP en el rango 2xx. Las solicitudes con errores devuelven códigos de estado en los rangos 4xx y 5xx. Las solicitudes que
requieren un redireccionamiento devuelven códigos de estado en el rango 3xx. Las respuestas de error
suelen incluir un documento JSON en el cuerpo de la respuesta, que contiene un objeto de error
con información sobre el error.
En las respuestas de la API de BigQuery, un objeto de error suele ser uno de los siguientes:
- Un objeto
errors, que contiene un array de objetosErrorProto. - Un objeto
errorResults, que contiene un solo objetoErrorProto.
La columna Motivo de las tablas de códigos de estado de esta página se asigna a la propiedad reason de un objeto ErrorProto. Si usas la
herramienta de línea de comandos de bq para verificar el estado del trabajo, usa
la marca --format=prettyjson (por ejemplo,
bq --format=prettyjson show -j <var>JOB_ID</var>) o --apilog=stdout para ver
el objeto de error y su propiedad reason.
En la siguiente tabla, se describen los elementos que pueden aparecer en el cuerpo de la respuesta de un error. Los campos se deben usar juntos para ayudar a determinar el problema. Además, los valores de ejemplo de la siguiente tabla son ilustrativos y no constituyen una lista exhaustiva de todos los valores posibles.
| Elemento | Descripción |
|---|---|
code |
Un valor de código de estado HTTP, sin la descripción textual. Los valores de ejemplo incluyen: 400 (solicitud incorrecta), 403 (prohibido) y 404 (no encontrado). |
error |
Es un contenedor para la información del error. |
errors |
Es un contenedor para los detalles del error. |
errores.domain |
Es el alcance del error. Entre los valores de ejemplo, se incluyen global y usageLimits. |
errores.location |
Es el elemento específico dentro de locationType que causó el error. Por ejemplo, si especificas un valor no válido para un parámetro, el location será el nombre del parámetro.Entre los valores de ejemplo, se incluyen Authorization y project. |
errores.locationType |
Es la ubicación o parte de la solicitud que causó el error. Úsala con location para identificar el error.Entre los valores de ejemplo, se incluyen header y parameter. |
errores.message |
Descripción del error. Entre los valores de ejemplo, se incluyen Invalid argument, Access Denied y Not Found: Dataset myproject:foo. |
errores.reason |
Es un identificador único para la causa del error. Entre los valores de ejemplo, se incluyen invalid, accessDenied y notFound. |
message |
Es la descripción del error. Igual que errors.message. |
Códigos de estado y error HTTP
En esta sección, se incluye una lista no exhaustiva de los códigos de estado y error de HTTP de
la API de BigQuery. Se omiten los códigos de información 1xx y de éxito 2xx. Para obtener más información, consulta los códigos de estado de respuesta
en RFC 7231 §6, RFC 7232 §4,
RFC 7233 §4, RFC 7235 §3 y RFC 6585.
400: Solicitud incorrecta
| Motivo | Código de estado HTTP | Descripción | Soluciona problemas |
|---|---|---|---|
badRequest |
400 |
Una declaración DML intenta modificar filas que se transmitieron recientemente con la
API de |
Migra a la API de BigQuery Storage Write (gRPC), espera unos minutos para que se vacíe el búfer de transmisión o filtra tu declaración para excluir las filas transmitidas recientemente. Para obtener más información, consulta Sentencias DML en tablas con un búfer de transmisión. |
invalid |
400 |
La solicitud contiene una entrada no válida que no es una consulta no válida, incluidos los siguientes casos:
|
Asegúrate de que los esquemas proporcionados coincidan con las columnas y los modos existentes, aplana las estructuras
que superen los 15 niveles de anidamiento (o almacénalas como |
invalidQuery |
400 |
Una consulta en SQL falla en las verificaciones de validación o ejecución por uno de los siguientes motivos:
|
Verifica la ubicación |
jobBackendError |
400 |
En |
Vuelve a intentar el trabajo con un |
jobInternalError |
400 |
En |
Vuelve a intentar el trabajo con un |
preconditionFailed |
400 |
No se cumple una condición previa de la solicitud, incluidos los siguientes casos:
|
Recupera el recurso |
resourceInUse |
400 |
Una solicitud de eliminación se orienta a un recurso que aún está activo o propagado:
El error devuelve lo siguiente: |
Vacía el conjunto de datos antes de borrarlo (o establece
|
resourcesExceeded |
400 |
Un trabajo supera los límites de recursos de ejecución en una de las siguientes áreas:
El error devuelve lo siguiente: |
Simplifica las consultas, agrupa las operaciones de DML por lotes, reduce las columnas o particiones analizadas, evita los trabajos simultáneos en la misma sesión o aprovisiona capacidad de ranuras dedicada para las cargas de trabajo con un uso intensivo de shuffle. Para conocer los pasos por subtipo, consulta Soluciona problemas de recursos excedidos y La consulta excede los recursos de memoria. |
storageUnusable |
400 |
El almacenamiento interno de BigQuery que contiene los datos de la tabla no está disponible de forma temporal debido a un problema de almacenamiento del servicio. El error devuelve lo siguiente:
|
Vuelve a intentar el trabajo con la retirada exponencial truncada. Para obtener más información, consulta El almacenamiento de tablas no se puede usar. |
streamingDataUnavailable |
400 |
Los datos transmitidos recientemente en el almacenamiento optimizado para escritura no están disponibles de forma temporal
para un trabajo de lectura. El error devuelve lo siguiente: |
Vuelve a intentar el trabajo con un |
tableUnavailable |
400 |
BigQuery no puede leer una tabla cuyos datos no administra, incluidos los siguientes casos:
|
Vuelve a intentar recuperar el esquema o los tiempos de espera de la tabla de copia de seguridad con
la retirada exponencial
truncada, o verifica las rutas de URI de Cloud Storage de |
userOwnedResourceError |
400 |
Un recurso externo de tu propiedad devuelve un error cuando BigQuery accede a él. El error devuelve lo siguiente: |
Inspecciona resource_type y resource_name en el mensaje de error para identificar el recurso externo y resolver el error subyacente informado en external_error. Para obtener más información, consulta Error de recurso externo propiedad del usuario. |
vortexDataUnavailable |
400 |
Los datos que se transmitieron recientemente con la API de BigQuery Storage Write (gRPC) al almacenamiento optimizado para escritura
no están disponibles de forma temporal para una consulta. El error devuelve lo siguiente: |
Vuelve a intentar el trabajo de consulta con un |
billingTierLimitExceeded |
400 |
Una consulta on demand supera el
límite máximo de uso de CPU por datos
analizados. El error devuelve lo siguiente: |
Refactoriza tu SQL para quitar productos cartesianos no deseados, uniones inexactas, funciones analíticas sin particiones o UDF de JavaScript pesadas, o cambia a precios basados en la capacidad (ranuras). Para obtener más información, consulta La consulta excede los recursos de CPU y Evita los antipatrones de SQL. |
bytesBilledLimitExceeded |
400 |
La estimación de bytes de límite superior previa a la ejecución de una consulta supera
|
Obtén una vista previa de los bytes estimados con una
ejecución de prueba, selecciona solo las columnas
necesarias y filtra las columnas particionadas para
reducir
el procesamiento de datos, o bien aumenta |
jobRateLimitExceeded |
400 |
En
|
Reduce los envíos simultáneos (o usa la prioridad por lotes o el ajuste de escala automático de ranuras para
las consultas continuas) y vuelve a intentar el trabajo con un |
timeout |
400 |
Una operación excede su límite de tiempo de ejecución, incluidos los siguientes casos:
|
Filtra por columnas particionadas o agrupadas, y divide las consultas complejas o de varias declaraciones en etapas más pequeñas, o especifica un esquema explícito y URIs de origen más estrechos cuando crees tablas externas. Para obtener más información, consulta La consulta supera el límite de tiempo de ejecución y Soluciona problemas de cuota y limita errores. |
invalidUser |
400 |
Se configuró una consulta programada con credenciales de usuario no válidas. |
Actualiza las credenciales del usuario para la consulta programada. Para obtener más información, consulta Programa consultas. |
required |
400 |
Falta una entrada obligatoria antes de la ejecución:
El error devuelve lo siguiente: |
Verifica el cuerpo de la solicitud y los parámetros de consulta obligatorios en la referencia de la API de BigQuery o en la documentación de la biblioteca cliente, y, luego, inspecciona el objeto de configuración antes de llamar a la API. Para obtener más información, consulta Falta un parámetro obligatorio. |
401 — Unauthorized
El siguiente es un ejemplo de una respuesta de error que recibes si tu solicitud no tiene credenciales de autenticación válidas.
401 Unauthorized
{
"error": {
"errors": [
{
"domain": "global",
"reason": "unauthenticated",
"message": "Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential."
}
],
"code": 401,
"message": "Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential.",
"status": "UNAUTHENTICATED"
}
}
| Motivo | Código de estado HTTP | Descripción | Soluciona problemas |
|---|---|---|---|
unauthenticated |
401 |
La autenticación de la solicitud falla por uno de los siguientes motivos:
|
Actualiza tus credenciales predeterminadas de la aplicación o de OAuth, otorga
|
403: Prohibido
Este es un ejemplo de una respuesta de error que recibes si no tienes permiso para acceder al recurso solicitado.
403 Forbidden
{
"error": {
"errors": [
{
"domain": "global",
"reason": "accessDenied",
"message": "Access Denied: Dataset myproject:mydataset: User does not have bigquery.datasets.get permission in project myproject."
}
],
"code": 403,
"message": "Access Denied: Dataset myproject:mydataset: User does not have bigquery.datasets.get permission in project myproject."
}
}
| Motivo | Código de estado HTTP | Descripción | Soluciona problemas |
|---|---|---|---|
responseTooLarge |
403 |
Una respuesta de lectura de consulta o tabla supera los límites de tamaño de una de las siguientes maneras:
El error devuelve lo siguiente: |
Especifica una tabla de destino (y establece
|
apiLimitExceeded |
403 |
Una solicitud supera uno de los siguientes límites de API o metadatos:
El error devuelve lo siguiente: |
Vuelve a intentar las solicitudes con errores con retirada exponencial truncada, cargas y lecturas por lotes, simplifica las políticas de seguridad detalladas de IAM por tabla o a nivel de fila, y espera la ventana móvil antes de agregar réplicas de conjuntos de datos. Para obtener más información, consulta Errores de límite de evaluación de metadatos y de frecuencia de la API y Errores de límite de creación de réplicas de conjuntos de datos entre regiones. |
quotaExceeded |
403 |
Tu proyecto supera una de las siguientes cuotas de uso:
El error devuelve lo siguiente: |
Inspecciona el error |
rateLimitExceeded |
403 |
Se rechaza una solicitud por uno de los siguientes límites de frecuencia o simultaneidad:
|
Disminuye el porcentaje de solicitudes y vuelve a intentarlo con una retirada exponencial truncada, o ejecuta consultas no urgentes con prioridad por lotes y ajusta la simultaneidad de las reservas o el ajuste de escala automático de ranuras. Para obtener más información, consulta Soluciona problemas de cuota y limita errores y Admisión de consultas denegada. |
accessDenied |
403 |
Se deniega el acceso a un recurso de BigQuery por uno de los siguientes motivos:
El error devuelve lo siguiente: |
Inspecciona los
registros de auditoría de Cloud
( |
policyViolation |
403 |
Un perímetro de seguridad o una política de la organización bloquean la solicitud:
|
Filtra el Explorador de registros por |
billingNotEnabled |
403 |
El proyecto no tiene una facturación activa para la operación solicitada:
El error devuelve lo siguiente: |
Habilita la facturación para el proyecto en la consola deGoogle Cloud para actualizar desde la zona de pruebas de BigQuery y, luego, actualiza los tiempos de vencimiento predeterminados para tus tablas, vistas y particiones. Para obtener más información, consulta La facturación no está habilitada para el proyecto. |
blocked |
403 |
BigQuery agregó de forma temporal la operación que se intentó realizar a una
lista de bloqueo para evitar una interrupción del servicio. El error devuelve lo siguiente: |
Comunícate con el equipo de Atención al cliente de Cloud con la marca de tiempo exacta, el ID del proyecto y el ID del trabajo de BigQuery para investigar la regla de mitigación administrativa. Para obtener más información, consulta Se bloqueó la solicitud para proteger el funcionamiento del sistema. |
termsOfServiceNotAccepted |
403 |
No se aceptaron las Condiciones del Servicio de BigQuery para el proyecto. El error devuelve: |
Accede a la consola deGoogle Cloud , selecciona tu país y la casilla de verificación de las Condiciones del Servicio en la página de bienvenida si se te solicita, y haz clic en Aceptar y continuar. Para obtener más información, consulta No se aceptaron las Condiciones del Servicio de BigQuery. |
404: No encontrado
A continuación, se muestra un ejemplo de una respuesta de error que recibes si intentas recuperar un conjunto de datos o un recurso que no existe.
404 Not Found
{
"error": {
"errors": [
{
"domain": "global",
"reason": "notFound",
"message": "Not Found: Dataset myproject:foo"
}
],
"code": 404,
"message": "Not Found: Dataset myproject:foo"
}
}
| Motivo | Código de estado HTTP | Descripción | Soluciona problemas |
|---|---|---|---|
notFound |
404 |
No se puede encontrar un recurso solicitado por uno de los siguientes motivos:
El error devuelve lo siguiente: |
Verifica el identificador y la ubicación exactos del proyecto, el conjunto de datos y la tabla que distinguen mayúsculas de minúsculas, restablece las tablas borradas dentro de la ventana de viaje en el tiempo, vuelve a ejecutar las consultas cuyas tablas de resultados almacenadas en caché vencieron o confirma que existen archivos externos de Cloud Storage o Google Drive. Para obtener más información, consulta No se encontró la tabla, No se encontró la ubicación y No se encontró el trabajo. |
409: Conflicto
A continuación, se muestra un ejemplo de una respuesta de error que recibes si intentas crear un recurso que ya existe.
409 Conflict
{
"error": {
"errors": [
{
"domain": "global",
"reason": "duplicate",
"message": "Already Exists: Dataset myproject:mydataset"
}
],
"code": 409,
"message": "Already Exists: Dataset myproject:mydataset"
}
}
| Motivo | Código de estado HTTP | Descripción | Soluciona problemas |
|---|---|---|---|
abortd |
409 |
Una operación se detiene debido a una modificación o un conflicto simultáneos (se devuelve
con el motivo escrito |
Vuelve a intentar la operación después de que finalice la operación en conflicto con la retirada exponencial truncada o revierte las transacciones con varias declaraciones detenidas antes de volver a intentarlo. Para obtener más información, consulta Se anuló la operación. |
duplicate |
409 |
Una solicitud entra en conflicto con un recurso existente de una de las siguientes maneras:
El error devuelve lo siguiente: |
Usa un nombre de recurso diferente, usa |
499: El cliente cerró la solicitud
| Motivo | Código de estado HTTP | Descripción | Soluciona problemas |
|---|---|---|---|
stopped |
499 |
Un trabajo se detiene antes de completarse por uno de los siguientes motivos (el sondeo
El error devuelve lo siguiente: |
Aumenta las opciones de tiempo de espera de la cola de proyectos o |
500: Error interno del servidor
| Motivo | Código de estado HTTP | Descripción | Soluciona problemas |
|---|---|---|---|
internalError |
500 |
Se produjo un error interno en BigQuery. El error devuelve lo siguiente:
|
Espera según los requisitos de retirada en el Acuerdo de Nivel de Servicio de BigQuery y vuelve a intentarlo con la retirada exponencial truncada, o usa Reservas para reducir la frecuencia de errores transitorios. Para obtener más información, consulta Soluciona errores internalError. |
501: No implementado
| Motivo | Código de estado HTTP | Descripción | Soluciona problemas |
|---|---|---|---|
notImplemented |
501 |
Una solicitud intenta usar una función o una operación no implementada para el recurso objetivo, como las siguientes:
El error devuelve lo siguiente: |
Materializa las fuentes de copia de tablas no compatibles con |
503: Servicio no disponible
| Motivo | Código de estado HTTP | Descripción | Soluciona problemas |
|---|---|---|---|
backendError |
503 |
El servicio no está disponible temporalmente por uno de los siguientes motivos:
El error devuelve lo siguiente: |
Vuelve a intentar las solicitudes con la
retirada exponencial
truncada y vuelve a intentar los trabajos con errores con un |