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 Cloud de Confiance 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:
- An
errorsobject, which contains an array ofErrorProtoobjects. - An
errorResultsobject, which contains a singleErrorProtoobject.
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 |
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:
|
Ensure provided schemas match existing columns and modes, flatten structures
exceeding 15 levels of nesting (or store them as |
invalidQuery |
400 |
A SQL query fails validation or execution checks for one of the following reasons:
|
Check the |
jobBackendError |
400 |
In |
Retry the job with a new |
jobInternalError |
400 |
In |
Retry the job with a new |
preconditionFailed |
400 |
A request precondition isn't met, including the following cases:
|
Fetch the current resource |
resourceInUse |
400 |
A delete request targets a resource that is still active or populated:
The error returns: |
Empty the dataset before deleting it (or set
|
resourcesExceeded |
400 |
A job exceeds execution resource limits in one of the following areas:
The error returns: |
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:
|
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: |
Retry the job with a new |
tableUnavailable |
400 |
BigQuery can't read a table whose data it doesn't manage, including the following cases:
|
Retry schema fetch or backing-table timeouts using
truncated exponential
backoff, or verify |
userOwnedResourceError |
400 |
An external resource that you own returns an error when accessed by
BigQuery. The error returns: |
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: |
Retry the query job with a new |
billingTierLimitExceeded |
400 |
An on-demand query exceeds the
maximum CPU usage per scanned
data limit. The error returns: |
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
|
Preview estimated bytes with a
dry run, select only needed
columns and filter on partitioned columns to
reduce
data processed, or raise |
jobRateLimitExceeded |
400 |
In
|
Reduce concurrent submissions (or use batch priority or slot autoscaling for
continuous queries), and retry the job with a new |
timeout |
400 |
An operation exceeds its execution time limit, including the following cases:
|
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:
The error returns: |
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:
|
Refresh your OAuth or Application Default Credentials, grant
|
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: |
Specify a destination table (and set
|
apiLimitExceeded |
403 |
A request exceeds one of the following API or metadata limits:
The error returns: |
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: |
Inspect the error |
rateLimitExceeded |
403 |
A request is rejected for one of the following rate or concurrency limits:
|
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 error returns: |
Inspect
Cloud Audit Logs
( |
policyViolation |
403 |
A security perimeter or organization policy blocks the request:
|
Filter Logs Explorer by |
billingNotEnabled |
403 |
The project lacks active billing for the requested operation:
The error returns: |
Enable billing for the project in the Cloud de Confiance 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: |
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: |
Sign in to the Cloud de Confiance 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 error returns: |
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 |
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:
The error returns: |
Use a different resource name, use |
499 — Client closed request
| Reason | HTTP Status Code | Description | Troubleshooting |
|---|---|---|---|
stopped |
499 |
A job stops before completion for one of the following reasons (polling
The error returns: |
Increase |
500 — Internal server error
| Reason | HTTP Status Code | Description | Troubleshooting |
|---|---|---|---|
internalError |
500 |
An internal error occurred within BigQuery. The error returns:
|
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:
The error returns: |
Materialize unsupported table copy sources using |
503 — Service unavailable
| Reason | HTTP Status Code | Description | Troubleshooting |
|---|---|---|---|
backendError |
503 |
The service is temporarily unavailable for one of the following reasons:
The error returns: |
Retry requests using
truncated exponential
backoff, and retry failed jobs with a new |