Hi All, The Iceberg REST spec doesn't appear to define 429 as a valid response status for rename operations, and I don't think it's an ideal choice either, since it typically indicates rate-limiting issues rather than conflicting updates.
In my opinion, 409 would be the most appropriate status code, but the REST spec reserves it for a different purpose. Perhaps 428 Precondition Required could be used to signal a conflict, but that status is generally intended for GET-then-PUT concurrency scenarios, which doesn't seem to match this case. I think we'll be diverging from the Iceberg spec either way, since it doesn't define a response code for conflicting rename operations. Given that, it's probably better to use a status code that isn't defined by the spec at all (such as 429) than to reuse one that the spec already assigns a different meaning to. Considering this, I vote for 429 as the least worst option. As of ENTITY_CANNOT_BE_RESOLVED, it sounds like a 404 for me too. However, the comment suggests that it may be used for conflict scenarios as well, and client should retry: // the specified entity (and its path) cannot be resolved. There is a possibility that by the // time a call is made by the client to the persistent storage, something has changed due to // concurrent modification(s). The client should retry in that case. ENTITY_CANNOT_BE_RESOLVED(4), Thanks, Nandor Dmitri Bourlatchkov <[email protected]> ezt írta (időpont: 2026. jún. 10., Sze, 0:43): > > Hi All, > > I reviewed PR [4646] (but did not leave any comments in GH, replying here) > and the current 500 error is most certainly not correct for this failure > mode. 503 is not ideal either, as I commented earlier. > > From the PR I gather that people are generally uncomfortable returning a > 409 response because it has a narrow meaning in the Iceberg REST API spec. > It is a fair point. > > Re: the TARGET_ENTITY_CONCURRENTLY_MODIFIED case. How about 429 (Too Many > Requests)? > > 429 is clearly retryable and does not carry any implications about the > state of the system after handling the request. > > The message could say "Unable to rename entity due to overlapping > concurrent modifications". We do not have to set the Retry-After header. > > Re: ENTITY_CANNOT_BE_RESOLVED. I believe this is a solid 404 case. > > WDYT? > > [4646] https://github.com/apache/polaris/pull/4646 > > Cheers, > Dmitri. > > > On Tue, Jun 9, 2026 at 12:02 AM Dmitri Bourlatchkov <[email protected]> > wrote: > > > Hi Nandor, > > > > Good question :) > > > > I did not read the PR yet, but my gut feel is towards the 409 error code > > because 5xx generally means a fundamental issue with the service that > > goes beyond the scope of client requests. > > > > In a more general perspective, traditional HTTP status codes are often too > > narrow to express all the API minute error details. My personal view is > > that a rich payload object in the response can be useful in such cases... > > but again that will require a spec change. > > > > That said, if the request does not require additional client input for a > > retry, Polaris should retry. I assume we can refactor the code to clearly > > distinguish retryable and non-retryable failures on the server side. That > > part should not require spec changes. > > > > Cheers, > > Dmitri. > > > > On Mon, Jun 8, 2026 at 9:48 AM Nándor Kollár <[email protected]> > > wrote: > > > >> Hi all, > >> > >> I'd like to ask for the community's opinion on the appropriate > >> response status code for table/view rename operations when there is a > >> conflicting operation in progress. > >> > >> A PR was recently raised [1], which I believe highlighted the question > >> of what the correct status code should be in such conflict scenarios. > >> To me, the Iceberg REST Catalog specification does not clearly address > >> this case. Neither 409 Conflict nor 503 Service Unavailable seems > >> entirely appropriate for indicating to the client that the operation > >> could not be completed due to a conflict and that retrying the > >> operation may succeed. > >> > >> I think 409 Conflict might be the better choice, but that would > >> require a change to the specification. It would also end up serving > >> two different purposes: a non-retriable scenario, where the target > >> name is already reserved, and a retriable scenario, where the > >> operation failed due to a temporary conflict. What do you think? > >> > >> [1] https://github.com/apache/polaris/pull/4646 > >> > >> Thanks, > >> Nandor > >> > > -- Kollár Nándor
