Thanks for raising this, Vignesh! Mapping it to 500 makes sense to me now. It's always safer to use 500 in the federation use case. 503/502/504 may involve retries, which require extra care to implement correctly.
Yufei On Fri, Jul 24, 2026 at 10:45 AM vignesh a <[email protected]> wrote: > Hi all, > > Context: https://github.com/apache/polaris/pull/5145 > > While reviewing a fix for IcebergExceptionMapper (PR #5145 > <https://github.com/apache/polaris/pull/5145>- mapping > CommitStateUnknownException to HTTP 500 instead of 400), Dimitri raised a > question that I think deserves wider input... > > Background: the Iceberg REST spec types CommitStateUnknownException as > 500/502/504 on commit endpoints, and Iceberg's client-side commit error > handler maps 500/502/503/504 to it. Polaris currently maps it to 400, so > clients receive BadRequestException for commits that may have been applied > - which can lead to unsafe retries. > > Is this exception reachable? Nothing in Polaris core throws it today, so > the mapping is dead for native catalogs. It is reachable through > federation: > > Iceberg REST federation: ErrorHandlers maps upstream 5xx responses to > CommitStateUnknownException, so a federated REST catalog returning > 500/502/503/504 on commit surfaces through Polaris's own REST layer. > > Hive federation: HiveFederatedCatalogFactory embeds Iceberg's HiveCatalog, > whose HiveTableOperations/HiveViewOperations throw it on uncertain commit > outcomes. > > Open question: when the trigger is an upstream 502/503/504, should Polaris > propagate the original status code or normalize to 500? The exception does > not carry the original status today, so propagation would require threading > it through. The spec lists 500/502/504 as valid for this error, and Iceberg > clients treat them identically on commit paths, so semantics are preserved > either way. The question is whether preserving the original code carries > enough operational value to justify the extra plumbing. > > In my POV: normalize to 500 (as in the PR #5145 > <https://github.com/apache/polaris/pull/5145> ). It satisfies the spec and > clients behave correctly. Propagating the original code can be a follow-up > if people want it. I'd like to hear opinions, especially from anyone > running federation in production. > > Re: If there's interest, I will audit the remaining exception-to-status > mappings in IcebergExceptionMapper against the spec and Iceberg's > client-side handlers as a follow-up. > > Rgds, > Vignesh >
