We can use `IcebergErrorResponse` to differentiate between route doesnt exists (404) and resource/warehouse doesnt exists (404). This is what the spec PR describes, https://github.com/apache/iceberg/pull/15746/files#diff-02549ca620d020dc9ead80088cc14e311e12a69651fa8d394cd41a4308debb2eR165-R173
For example, `google.com/v1/config` <http://google.com/v1/config> doesnt exist, so ``` python3 -c "import urllib.request; urllib.request.urlopen(' http://google.com/v1/config')" ``` returns `urllib.error.HTTPError: HTTP Error 404: Not Found` And I would expect an IRC endpoint to return `NoSuchWarehouseError` instead, with `"type": "NoSuchWarehouseException"`. Best, Kevin Liu On Sat, Mar 28, 2026 at 10:08 AM Steven Wu <[email protected]> wrote: > Chatted with Yufei offline. The `warehouse/catalog` is a hidden concept in > the REST spec. If we could redo it, including it in the path (instead of as > a query parameter) might make more sense. E.g., The endpoint could look > like "/v1/{prefix}/config," where a 404 status would be perfect. > > Since it is too late to change that, I agree 404 is fine here. > > On Fri, Mar 27, 2026 at 10:00 AM Ryan Blue <[email protected]> wrote: > >> I think the difference between those examples and the config route is >> that those examples identify resources that do not exist (namespace in both >> cases). We also have cases where you could get a 404 indicating a namespace >> or a table does not exist, but that indicates that the resource you're >> looking for either does not exist (table) or can't exist (namespace >> preventing table from being present). >> >> The config endpoint always exists, which is why this is odd. I think you >> could argue that this is okay because it isn't really a resource that has >> create/update/delete operations. I just don't know what the "correct" way >> to handle this is in REST APIs. But then I've never been one that's too >> strict about REST principles. >> >> On Thu, Mar 26, 2026 at 3:44 PM Yufei Gu <[email protected]> wrote: >> >>> I'd be cautious about 204 since it indicates a successful response. 404 >>> seems fine to me. IRC spec uses it in multiple places, like [1] and [2] to >>> indicate that certain entities do not exist. >>> >>> 1. >>> https://github.com/apache/iceberg/blob/9534c9b3adc29d127ecc541ce131f49fd72f1980/open-api/rest-catalog-open-api.yaml#L539 >>> 2. >>> https://github.com/apache/iceberg/blob/9534c9b3adc29d127ecc541ce131f49fd72f1980/open-api/rest-catalog-open-api.yaml#L490 >>> >>> Yufei >>> >>> >>> On Thu, Mar 26, 2026 at 2:03 PM Steven Wu <[email protected]> wrote: >>> >>>> >>>> 404 may not be the best fit, as it generally indicates that the >>>> endpoint itself could not be found. The endpoint receiving the query >>>> parameters exists, and a lack of results is a valid outcome of the >>>> search/filter operation, not a client error in forming the request URI. >>>> >>>> Maybe return 204 No Content as the request itself was valid and >>>> successfully processed. >>>> >>>> On Thu, Mar 26, 2026 at 1:48 PM Ryan Blue <[email protected]> wrote: >>>> >>>>> This seems reasonable to me. I don't know if 404 is the right response >>>>> since the endpoint always exists, but it's fine with me. >>>>> >>>>> On Wed, Mar 25, 2026 at 6:04 PM Yufei Gu <[email protected]> wrote: >>>>> >>>>>> It seems reasonable to add the 404 response. I noticed that the >>>>>> warehouse parameter is optional. I assume this is meant for catalog >>>>>> implementations that support exactly one catalog or warehouse here so >>>>>> that >>>>>> client is OK to skip it, though please correct me if I am mistaken. In >>>>>> that >>>>>> case, a 404 would still make sense when that single warehouse is not yet >>>>>> ready. >>>>>> >>>>>> parameters: >>>>>> - name: warehouse >>>>>> in: query >>>>>> required: false >>>>>> >>>>>> >>>>>> Yufei >>>>>> >>>>>> >>>>>> On Tue, Mar 24, 2026 at 8:33 AM Kevin Liu <[email protected]> >>>>>> wrote: >>>>>> >>>>>>> Thanks for raising this proposal! I think it makes sense to add this >>>>>>> to the spec and be explicit about the error case. I found the place >>>>>>> where >>>>>>> Apache Polaris throws `NotFoundException` for the `/v1/config` endpoint. >>>>>>> The specific error `type` field can be used to disambiguate a route 404 >>>>>>> (URL doesn't exist) from a resource 404 (URL is valid, but the server >>>>>>> cannot find the warehouse). >>>>>>> >>>>>>> Best, >>>>>>> Kevin Liu >>>>>>> >>>>>>> [1] >>>>>>> https://github.com/apache/polaris/blob/67daa9bb479eaa0ee6c4428984e253afc01b6efd/runtime/service/src/main/java/org/apache/polaris/service/catalog/iceberg/IcebergCatalogHandler.java#L1360 >>>>>>> >>>>>>> On Tue, Mar 24, 2026 at 4:34 AM Oğuzhan Ünlü < >>>>>>> [email protected]> wrote: >>>>>>> >>>>>>>> Hi everyone, >>>>>>>> >>>>>>>> I'd like to propose a small addition to the REST catalog spec: >>>>>>>> documenting HTTP 404 as a valid response for the /v1/config endpoint >>>>>>>> when a >>>>>>>> requested warehouse does not exist. >>>>>>>> >>>>>>>> The Rationale >>>>>>>> >>>>>>>> The /v1/config endpoint allows an optional query parameter for a >>>>>>>> warehouse identifier, e.g. /v1/config?warehouse=mywarehouse. But the >>>>>>>> openapi spec does not specify what should happen if the requested >>>>>>>> warehouse >>>>>>>> does not exist. >>>>>>>> >>>>>>>> Snowflake Open Catalog already returns a 404 for non-existent >>>>>>>> warehouses: >>>>>>>> >>>>>>>> ``` >>>>>>>> { >>>>>>>> "error": { >>>>>>>> "message": "Unable to find warehouse >>>>>>>> NONEXISTENT_WAREHOUSE_12345", >>>>>>>> "type": "NotFoundException", >>>>>>>> "code": 404 >>>>>>>> } >>>>>>>> } >>>>>>>> ``` >>>>>>>> >>>>>>>> This proposal therefore formalizes what Snowflake Open Catalog is >>>>>>>> already doing in production. It seems sensible to formalize the 404 >>>>>>>> response code, because this is consistent with other Iceberg REST >>>>>>>> endpoints >>>>>>>> which allow a 404 response code for missing resources (tables, >>>>>>>> namespaces, >>>>>>>> views). >>>>>>>> >>>>>>>> The Proposed Solution (PR-15746) >>>>>>>> >>>>>>>> Add a NoSuchWarehouseResponse to the OpenAPI spec for the >>>>>>>> /v1/config endpoint, formalizing 404 as the response when a warehouse >>>>>>>> does >>>>>>>> not exist. You can view the PR here: >>>>>>>> https://github.com/apache/iceberg/pull/15746 . >>>>>>>> >>>>>>>> Looking forward to your thoughts. >>>>>>>> >>>>>>>> Best, >>>>>>>> Oguzhan >>>>>>>> >>>>>>>
