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 >>>>>> >>>>>
