HTTP status and error codes for BigQuery API

This page describes the HTTP status codes and error messages returned by the BigQuery API. You can use these codes to troubleshoot and resolve request failures, and verify API behavior.

For more information about non-API errors, client library connectivity errors, and Google Cloud console errors, see Error messages.

For more information about query errors, see Troubleshoot query errors.

For more information about streaming insert errors, see Troubleshoot streaming inserts.

Error response format

BigQuery uses the standard HTTP error reporting format for its API. Successful requests return HTTP status codes in the 2xx range. Failed requests return status codes in the 4xx and 5xx ranges. Requests that require a redirect return status codes in the 3xx range. Error responses usually include a JSON document in the response body, which contains an error object with information about the error.

In BigQuery API responses, an error object is typically one of the following:

The Reason column in the status code tables on this page maps to the reason property in an ErrorProto object. If you use the bq command-line tool to check job status, use the --format=prettyjson flag (for example, bq --format=prettyjson show -j <var>JOB_ID</var>) or --apilog=stdout to view the error object and its reason property.

The following table describes the elements that can appear in the response body of an error. Fields should be used together to help determine the problem. Also, the example values in the following table are meant for illustration and aren't an exhaustive list of all possible values.

Element Description
code An HTTP status code value, without the textual description.

Example values include: 400 (Bad Request), 403 (Forbidden), and 404 (Not Found).
error A container for the error information.
errors A container for the error details.
errors.domain The scope of the error. Example values include: global and usageLimits.
errors.location The specific item within the locationType that caused the error. For example, if you specify an invalid value for a parameter, the location will be the name of the parameter.

Example values include: Authorization and project.
errors.locationType The location or part of the request that caused the error. Use with location to pinpoint the error.

Example values include header and parameter.
errors.message Description of the error.

Example values include Invalid argument, Access Denied, and Not Found: Dataset myproject:foo.
errors.reason A unique identifier for the error cause.

Example values include invalid, accessDenied, and notFound.
message Description of the error. Same as errors.message.

HTTP status and error codes

This section contains a non-exhaustive list of HTTP status and error codes from the BigQuery API. The 1xx Informational and 2xx Success codes are omitted. For more information, see Response Status Codes in RFC 7231 §6, RFC 7232 §4, RFC 7233 §4, RFC 7235 §3, and RFC 6585.

400 — Bad Request

Reason HTTP Status Code Description Troubleshooting
badRequest 400

A DML statement attempts to modify rows that were recently streamed with the legacy tabledata.insertAll API and remain in the table's streaming buffer. The error returns: UPDATE or DELETE statement over table project.dataset.table would affect rows in the streaming buffer, which is not supported.

Migrate to the BigQuery Storage Write API (gRPC), wait a few minutes for the streaming buffer to flush, or filter your statement to exclude recently streamed rows. For more information, see DML statements on tables with a streaming buffer.

invalid 400

The request contains invalid input other than an invalid query, including the following cases:

  • A schema mismatch (Provided Schema does not match Table table).
  • A RECORD column, file, or routine that exceeds the 15-level nesting limit (Schema nested too deeply).
  • A destination table that is deleted or expires during a job (Destination deleted/expired during operation).

Ensure provided schemas match existing columns and modes, flatten structures exceeding 15 levels of nesting (or store them as JSON), and set destination table expiration times to outlive running jobs. For per-subtype steps, see Troubleshoot invalid input and schema errors.

invalidQuery 400

A SQL query fails validation or execution checks for one of the following reasons:

  • Invalid SQL syntax, identifiers, or data types.
  • Unsatisfied feature options or required partition filters.
  • Exceeded view nesting or partition output limits.
  • A concurrent DML transaction conflict (such as Concurrent conflicting update to details).

Check the [line:column] location for GoogleSQL syntax or type mismatches, satisfy required OPTIONS or partition filters, or roll back stalled sessions and retry conflicting DML jobs. For more information, see Invalid query errors and Transaction aborted due to concurrent update.

jobBackendError 400

In jobs.query or jobs.getQueryResults, a job was created and then failed during execution with a backendError. The error returns: The job encountered an error during execution. Retrying the job may solve the problem.

Retry the job with a new jobId using truncated exponential backoff, ensuring client retry logic handles HTTP 400 responses in addition to 5xx codes. For more information, see Troubleshoot jobBackendError and jobInternalError errors.

jobInternalError 400

In jobs.query or jobs.getQueryResults, a job was created and then failed during execution with an internal error. The error returns: The job encountered an internal error during execution and was unable to complete.

Retry the job with a new jobId using truncated exponential backoff. For more information, see Troubleshoot jobBackendError and jobInternalError errors.

preconditionFailed 400

A request precondition isn't met, including the following cases:

  • An If-Match ETag mismatch during a metadata update.
  • A missing CMEK encryption key required by organization policy.
  • A feature that isn't supported in the Standard edition.
  • A write to a failover dataset outside an Enterprise Plus primary reservation.
  • A materialized view query over a CDC base table with pending upserts.

Fetch the current resource etag before retrying, specify the required Cloud Key Management Service key, run the workload in an Enterprise or Enterprise Plus reservation, or wait a few minutes for pending CDC upserts to apply. For per-subtype steps, see Request precondition failed.

resourceInUse 400

A delete request targets a resource that is still active or populated:

  • A dataset that still contains tables, views, or routines.
  • A job that is still pending or running.

The error returns: resource_type resource_id is still in use.

Empty the dataset before deleting it (or set deleteContents=true, run bq rm -r -f -d, or execute DROP SCHEMA IF EXISTS dataset_name CASCADE), or wait for an active job to finish or cancel it before deleting job metadata. For more information, see Resource is still in use.

resourcesExceeded 400

A job exceeds execution resource limits in one of the following areas:

  • Per-table DML concurrency queues or session concurrency limits.
  • Worker, UDF, shuffle, or ML model memory budgets.
  • Table partition (10,000 partitions) or output column limits.
  • Cloud Key Management Service CMEK request rates, streaming reads, or cross-region data transfers.
  • Query planning complexity limits.

The error returns: Resources exceeded during query execution: details.

Simplify queries, batch DML operations, reduce scanned columns or partitions, avoid concurrent jobs in the same session, or provision dedicated slot capacity for shuffle-heavy workloads. For per-subtype steps, see Troubleshoot resources exceeded issues and Query exceeds memory resources.

storageUnusable 400

Internal BigQuery storage holding the table's data is temporarily unavailable due to a service-side storage issue. The error returns: Storage of resource_id is unusable because reason.

Retry the job using truncated exponential backoff. For more information, see Table storage is unusable.

streamingDataUnavailable 400

Recently streamed data in write-optimized storage is temporarily unavailable to a reading job. The error returns: Job failed because streaming data from table_source is temporarily unavailable. Retrying the job may solve the problem.

Retry the job with a new jobId using truncated exponential backoff, ensuring client retry logic handles HTTP 400 responses. For more information, see Streaming data is temporarily unavailable.

tableUnavailable 400

BigQuery can't read a table whose data it doesn't manage, including the following cases:

  • Fetching an Apache Iceberg or Delta Lake table schema times out.
  • A Hive-partitioned external table has no partition keys.
  • A Google-managed backing table is temporarily unavailable.

Retry schema fetch or backing-table timeouts using truncated exponential backoff, or verify key=value Cloud Storage URI paths and recreate Hive-partitioned external tables with at least one partition key. For more information, see External or backing table is unavailable.

userOwnedResourceError 400

An external resource that you own returns an error when accessed by BigQuery. The error returns: Error when accessing a user-owned external resource_type resource resource_name. The resource provided error: external_error.

Inspect resource_type and resource_name in the error message to identify the external resource, and resolve the underlying error reported in external_error. For more information, see User-owned external resource error.

vortexDataUnavailable 400

Data recently streamed using the BigQuery Storage Write API (gRPC) into write-optimized storage is temporarily unavailable to a query. The error returns: Job failed because vortex streaming data from table_source is temporarily unavailable. Retrying the job may solve the problem.

Retry the query job with a new jobId using truncated exponential backoff, ensuring client retry logic handles HTTP 400 responses. For more information, see Streaming data is temporarily unavailable.

billingTierLimitExceeded 400

An on-demand query exceeds the maximum CPU usage per scanned data limit. The error returns: Query exceeded resource limits. This query used cpu_seconds_used CPU seconds but would charge only analysis_megabytes_billed M Analysis bytes... cpu_seconds_used CPU seconds were used, and this query must use less than cpu_seconds_limit CPU seconds.

Refactor your SQL to remove unintended Cartesian products, inexact joins, unpartitioned window functions, or heavy JavaScript UDFs, or switch to capacity-based (slots) pricing. For more information, see Query exceeds CPU resources and Avoid anti-SQL patterns.

bytesBilledLimitExceeded 400

The pre-execution upper-bound byte estimate for a query exceeds maximumBytesBilled before execution starts. The error returns: Query exceeded limit for bytes billed: limit_bytes. required_bytes or higher required.

Preview estimated bytes with a dry run, select only needed columns and filter on partitioned columns to reduce data processed, or raise maximumBytesBilled to at least required_bytes. For more information, see Query exceeds maximum bytes billed limit.

jobRateLimitExceeded 400

In jobs.query or jobs.getQueryResults, a job fails for one of the following reasons:

  • The job exceeds a rate limit during execution (Job exceeded rate limits: Your scope exceeded quota for quota_metric...).
  • The query isn't admitted because the query queue concurrency or continuous-query slot limit is reached (for example, Query was not admitted as the maximum concurrency has been reached...).

Reduce concurrent submissions (or use batch priority or slot autoscaling for continuous queries), and retry the job with a new jobId using truncated exponential backoff. For more information, see Job exceeded rate limits and Query admission denied.

timeout 400

An operation exceeds its execution time limit, including the following cases:

  • A query or dry run exceeds the 6-hour execution limit.
  • A child job inside a multi-statement query times out.
  • External table schema auto-detection times out.

Filter on partitioned or clustered columns and split complex or multi-statement queries into smaller stages, or specify an explicit schema and narrower source URIs when creating external tables. For more information, see Query exceeds execution time limit and Troubleshoot quota and limit errors.

invalidUser 400

A scheduled query was configured with invalid user credentials.

Refresh the user credentials for the scheduled query. For more information, see Scheduling queries.

required 400

A required input is missing before execution:

  • A required field in an API request payload or URL wasn't provided.
  • A required configuration object in a client library is empty or unassigned.

The error returns: Required parameter is missing: parameter_name.

Verify required request body and query parameters in the BigQuery API reference or client library documentation, and inspect the configuration object before calling the API. For more information, see Required parameter is missing.

401 — Unauthorized

The following is an example of an error response that you receive if your request lacks valid authentication credentials.

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"
  }
}
Reason HTTP Status Code Description Troubleshooting
unauthenticated 401

Authentication for the request fails for one of the following reasons:

  • The request lacks valid authentication credentials or uses an expired OAuth 2.0 access token.
  • End-user credentials or service account impersonation permissions are missing.
  • The caller's user account is restricted or deleted.

Refresh your OAuth or Application Default Credentials, grant roles/iam.serviceAccountUser or roles/iam.serviceAccountTokenCreator when running with or impersonating a service account, or contact your administrator to restore a restricted account. For more information, see Troubleshoot unauthenticated errors.

403 — Forbidden

This is an example of an error response that you receive if you don't have permission to access the requested resource.

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."
  }
}
Reason HTTP Status Code Description Troubleshooting
responseTooLarge 403

A query or table read response exceeds size limits in one of the following ways:

The error returns: Response too large to return. details.

Specify a destination table (and set configuration.query.allowLargeResults to true for legacy SQL), remove ORDER BY or add LIMIT, or read large rows using the BigQuery Storage Read API or EXPORT DATA. For more information, see Query response is too large and Single-row response size limit exceeded.

apiLimitExceeded 403

A request exceeds one of the following API or metadata limits:

  • Per-minute API request rate limits.
  • Table or policy metadata evaluation quotas.
  • Cross-region dataset replica creation limits (Cannot add more than limit replicas for a region within window day(s)).

The error returns: API limit exceeded: details.

Retry failed requests with truncated exponential backoff, batch loads and reads, simplify granular per-table IAM or row-level security policies, and wait for the rolling window before adding dataset replicas. For more information, see API rate and metadata evaluation limit errors and Cross-region dataset replica creation limit errors.

quotaExceeded 403

Your project exceeds one of the following usage quotas:

The error returns: Quota exceeded: Your scope exceeded quota for quota_metric. For more information, see https://cloud.google.com/bigquery/docs/troubleshoot-quotas.

Inspect the error message to identify the exceeded quota, optimize high-scanning queries or upgrade from the sandbox, or adjust custom quotas on the Quotas page. For more information, see Custom daily query quota errors.

rateLimitExceeded 403

A request is rejected for one of the following rate or concurrency limits:

  • Short-term API or query job rate limits (Exceeded rate limits: too many quota_metric for this scope...).
  • Query queue concurrency or continuous-query reservation slot limits (for example, Query was not admitted as the maximum concurrency has been reached...).

Slow down the request rate and retry using truncated exponential backoff, or run non-urgent queries with batch priority and adjust reservation concurrency or slot autoscaling. For more information, see Troubleshoot quota and limit errors and Query admission denied.

accessDenied 403

Access to a BigQuery resource is denied for one of the following reasons:

  • The principal lacks required IAM permissions on the target project, dataset, or table.
  • An authorized view, row-level access policy, or column-level policy tag restricts access.
  • Cloud Key Management Service CMEK permissions or external data source permissions are missing.

The error returns: Access Denied: resource_type resource_id: details.

Inspect Cloud Audit Logs (protoPayload.authorizationInfo) and Policy Analyzer to identify the missing permission, and grant the least-privilege predefined BigQuery role. For more information, see Troubleshoot common Access Denied scenarios.

policyViolation 403

A security perimeter or organization policy blocks the request:

  • A VPC Service Controls perimeter restricts access (including Google Drive exports or external tables in VPC-SC projects).
  • An organization policy constraint such as constraints/gcp.resourceLocations disallows the operation.

Filter Logs Explorer by vpcServiceControlsUniqueIdentifier and check the Violation Analyzer, export or load data using a Cloud Storage bucket inside the perimeter, or select a region allowed by your organization policy constraints. For more information, see Troubleshoot policy violation errors.

billingNotEnabled 403

The project lacks active billing for the requested operation:

  • Billing isn't enabled for the project.
  • The project runs in the BigQuery sandbox, where tables, views, and partitions expire after 60 days (expiration time must be less than 60 days).

The error returns: Billing has not been enabled for this project. Enable billing at https://console.cloud.google.com/billing. details.

Enable billing for the project in the Google Cloud console to upgrade from the BigQuery sandbox, and then update the default expiration times for your tables, views, and partitions. For more information, see Billing isn't enabled for the project.

blocked 403

BigQuery temporarily added the attempted operation to a denylist to prevent a service outage. The error returns: Request was blocked to protect the system's operation. Please contact support at https://cloud.google.com/support.

Contact Cloud Customer Care with the exact timestamp, project ID, and BigQuery job ID to investigate the administrative mitigation rule. For more information, see Request was blocked to protect system operation.

termsOfServiceNotAccepted 403

The project hasn't accepted the BigQuery Terms of Service. The error returns: BigQuery Terms of Service have not been accepted.

Sign in to the Google Cloud console, select your country and the Terms of Service checkbox on the welcome page if prompted, and click Agree and continue. For more information, see BigQuery Terms of Service not accepted.

404 — Not Found

The following is an example of an error response that you receive if you try to retrieve a dataset or resource that doesn't exist.

404 Not Found

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "notFound",
        "message": "Not Found: Dataset myproject:foo"
      }
    ],
    "code": 404,
    "message": "Not Found: Dataset myproject:foo"
  }
}
Reason HTTP Status Code Description Troubleshooting
notFound 404

A requested resource can't be found for one of the following reasons:

  • The target dataset, table, or job doesn't exist or has expired.
  • An external Cloud Storage or Google Drive file URI doesn't exist.
  • The request location doesn't match the dataset or job location.

The error returns: Not found: resource_type resource_id.

Verify the exact case-sensitive project, dataset, and table identifier and location, restore deleted tables within the time travel window, rerun queries whose cached result tables expired, or confirm external Cloud Storage or Google Drive files exist. For more information, see Table not found, Location not found, and Job not found.

409 — Conflict

The following is an example of an error response that you receive if you try to create a resource that already exists.

409 Conflict

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "duplicate",
        "message": "Already Exists: Dataset myproject:mydataset"
      }
    ],
    "code": 409,
    "message": "Already Exists: Dataset myproject:mydataset"
  }
}
Reason HTTP Status Code Description Troubleshooting
abortd 409

An operation stops because of a concurrent modification or conflict (returned with reason spelled abortd).

Retry the operation after the conflicting operation finishes using truncated exponential backoff, or roll back stopped multi-statement transactions before retrying. For more information, see Operation was aborted.

duplicate 409

A request conflicts with an existing resource in one of the following ways:

  • Creating a dataset, table, or job resource that already exists.
  • Running a job with writeDisposition set to WRITE_EMPTY when the destination table already exists.

The error returns: Already Exists: resource_type resource_id.

Use a different resource name, use IF NOT EXISTS or CREATE OR REPLACE in DDL statements, change writeDisposition to WRITE_APPEND or WRITE_TRUNCATE, or let BigQuery generate a random jobId. For per-subtype steps, see Resource already exists.

499 — Client closed request

Reason HTTP Status Code Description Troubleshooting
stopped 499

A job stops before completion for one of the following reasons (polling jobs.get returns HTTP 200 with reason: stopped):

  • A caller explicitly cancels the job (User requested cancellation).
  • The job exceeds a configured execution or queue timeout (Job timed out after duration or Job timed out in the queue after duration).

The error returns: Job execution was cancelled: details.

Increase configuration.jobTimeoutMs or project queue timeout options (or optimize query runtime and concurrency), or check Cloud Audit Logs for jobservice.cancel calls. For per-subtype steps, see Job execution was canceled.

500 — Internal server error

Reason HTTP Status Code Description Troubleshooting
internalError 500

An internal error occurred within BigQuery. The error returns: An internal error occurred and the request could not be completed.

Wait according to the backoff requirements in the BigQuery Service Level Agreement and retry using truncated exponential backoff, or use Reservations to reduce transient error frequency. For more information, see Troubleshoot internalError errors.

501 — Not implemented

Reason HTTP Status Code Description Troubleshooting
notImplemented 501

A request attempts to use an unimplemented feature or operation for the target resource, such as the following:

  • Copying a table with a non-managed storage type.
  • Running an unsupported ALTER SEARCH INDEX option.

The error returns: Not Implemented: details.

Materialize unsupported table copy sources using CREATE TABLE destination_table AS SELECT * FROM source_table, or drop and recreate search indexes with DROP SEARCH INDEX and CREATE SEARCH INDEX. For per-subtype steps, see Feature or operation isn't implemented.

503 — Service unavailable

Reason HTTP Status Code Description Troubleshooting
backendError 503

The service is temporarily unavailable for one of the following reasons:

  • A service demand surge (load shedding) or internal resource exhaustion.
  • Intermittent network connectivity issues.
  • A transient backend component issue.

The error returns: Error encountered during execution. Retrying may solve the problem.

Retry requests using truncated exponential backoff, and retry failed jobs with a new jobId. If errors persist across retries, compare your 30-day failure rate against the BigQuery SLA and contact Cloud Customer Care; see Troubleshoot backendError errors.