The HTTP-to-Canonical code conversion (HttpJsonStatusCode.httpStatusToStatusCode()) is used only for error situations where a server returns a non-2xx HTTP status code. gax-java surfaces errors in terms of ApiExceptions, which are modeled precisely following the canonical status codes (go/canonical-codes). (That is, there's a one-to-one correspondence between the canonical error codes and the Java exceptions.) That's why and the only reason we need to interpret HTTP codes as canonical codes.

The previous implementation wasn't following the standardized mapping (go/http-canonical-mapping). Now we are trying to make this consistent across all languages. Therefore, this does introduce a breaking change in terms of which HTTP server response code is surfaced as which Java exception.

However, for the conventional commit message and the PR title, I'm not marking as a breaking change, as gax-httpjson hasn't GA'ed.

b/205195666

Appendix

The locations where the HTTP-to-canonical conversion takes place:

• HttpJsonExceptionCallable.onFailure(): HTTP error status is interpreted as canonical error status (via exception).

    public void onFailure(Throwable throwable) {
      if (throwable instanceof HttpResponseException) {
        HttpResponseException e = (HttpResponseException) throwable;
        // HttpResponseException.getStatusCode() returns HTTP code
        StatusCode statusCode = HttpJsonStatusCode.of(e.getStatusCode());
        boolean canRetry = retryableCodes.contains(statusCode.getCode());
        String message = e.getStatusMessage();
        ApiException newException =
            message == null
                ? ApiExceptionFactory.createException(throwable, statusCode, canRetry)
                : ApiExceptionFactory.createException(message, throwable, statusCode, canRetry);
        super.setException(newException);

• HttpJsonOperationSnapshot.Builder.setError(): the builder takes an HTTP code. Note there's no usage of setError() within gax-java. It is supposed to take HTTP code, but for some legacy reason, it treats 0 as a special case to indicate success (which is not ideal).

    public Builder setError(int httpStatus, String errorMessage) {
      this.errorCode =
          httpStatus == 0 ? HttpJsonStatusCode.of(Code.OK) : HttpJsonStatusCode.of(httpStatus);
      this.errorMessage = errorMessage;
      return this;
    }