Skip to content

docs(bigquery): document structured error reasons and retryability on BigQueryException - #15125

Merged
lqiu96 merged 1 commit into
googleapis:mainfrom
lqiu96:docs/bq-2a-document-error-reasons-and-retryability
Nov 20, 2026
Merged

lqiu96 merged 1 commit into
googleapis:mainfrom
lqiu96:docs/bq-2a-document-error-reasons-and-retryability

Conversation

@lqiu96

@lqiu96 lqiu96 commented Nov 20, 2026

Copy link
Copy Markdown
Member

Clarifies error classification and retryability semantics in BigQueryException and BigQueryError.getReason() Javadocs (Javadoc-only, no behavioral changes).

Summary of changes

  • BigQueryException: document that BigQuery communicates transient vs. permanent failures through structured error reasons (getReason(), getError(), getErrors()) rather than HTTP status codes alone (for example, rate-limit errors may return HTTP 403 and job-execution errors surface with getCode() == 0).
  • BigQueryException: document that isRetryable() classifies only HTTP 500, 502, 503, 504, and low-level transport IOException failures as retryable, and that transient asynchronous job failures must be resubmitted as a new job with a new JobId rather than re-polling the failed job.
  • BigQueryError.getReason(): clarify that the error reason string is the primary signal alongside HTTP status for distinguishing transient from permanent failures.

Verification

  • Verified against BigQueryException.java (RETRYABLE_ERRORS, constructors) and BigQueryExceptionTest.java
  • mvn -pl java-bigquery/google-cloud-bigquery com.spotify.fmt:fmt-maven-plugin:check -Dlint checkstyle:check@checkstyle test-compile (0 Checkstyle violations)
  • javadoc -Xdoclint:syntax,html,reference on both modified files (0 warnings/errors)

@lqiu96
lqiu96 requested review from a team as code owners November 20, 2026 23:00

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request updates the Javadoc documentation for BigQueryError and BigQueryException to provide clearer guidance on how to handle and classify transient versus permanent failures using structured error reasons and HTTP status codes. There are no review comments, and I have no additional feedback to provide on these documentation improvements.

@lqiu96
lqiu96 merged commit c4d09b7 into googleapis:main Nov 20, 2026
197 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants