diff --git a/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/BigQueryError.java b/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/BigQueryError.java index 41465bfe11ac..fc0d6c906e2a 100644 --- a/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/BigQueryError.java +++ b/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/BigQueryError.java @@ -70,7 +70,12 @@ public BigQueryError(String reason, String location, String message) { } /** - * Returns short error code that summarizes the error. + * Returns a short error code that summarizes the error (for example, {@code rateLimitExceeded}, + * {@code backendError}, or {@code notFound}). + * + *
Inspect this reason alongside the HTTP status code when classifying transient versus + * permanent failures, because distinct BigQuery errors can share an HTTP status code or occur + * asynchronously in job status without an HTTP status code. * * @see BigQuery API HTTP status and * error codes diff --git a/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/BigQueryException.java b/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/BigQueryException.java index 212b4c4d3e6a..f7affea65b09 100644 --- a/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/BigQueryException.java +++ b/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/BigQueryException.java @@ -30,6 +30,17 @@ /** * BigQuery service exception. * + *
BigQuery often indicates whether a failure is transient or permanent through a structured + * error reason ({@link #getReason()}, {@link #getError()}, or {@link #getErrors()}) rather than the + * HTTP status code alone. For example, rate-limit errors may arrive with HTTP 403, and + * job-execution errors surfaced from job status have {@link #getCode()} equal to {@code 0}. + * + *
{@link #isRetryable()} classifies only HTTP 500, 502, 503, 504, and low-level transport {@link + * IOException} failures as retryable. When deciding whether to retry, inspect the structured error + * reason alongside the HTTP status code and consult the BigQuery error codes reference. Transient + * asynchronous job failures cannot be recovered by polling the failed job again. Resubmit the work + * as a new job with a new {@link JobId}. + * * @see BigQuery API HTTP status and * error codes * @see BigQuery client and