You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@iceberg.apache.org by "oguzhanunlu (via GitHub)" <gi...@apache.org> on 2026/03/23 21:10:28 UTC
[PR] API, OpenAPI: Add 404 response for /v1/config endpoint [iceberg]
oguzhanunlu opened a new pull request, #15746:
URL: https://github.com/apache/iceberg/pull/15746
## Summary
This PR proposes adding HTTP 404 as a documented response for the `/v1/config` endpoint in the REST Catalog OpenAPI specification, along with `NoSuchWarehouseException` in the API module.
## 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.
We noticed that Snowflake Open Catalog already returns a 404 for non-existent warehouses:
```json
{
"error": {
"message": "Unable to find warehouse NONEXISTENT_WAREHOUSE_12345",
"type": "NotFoundException",
"code": 404
}
}
```
This PR 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 respources (tables, namespaces, views).
## Our use case
At my company we triage Iceberg exceptions according to their type. For example, an exception for a missing resource might get triaged to the team responsible for providing that resource.
Currently, the Iceberg core library yields the generic `RESTException` if a warehouse does not exist. It is difficult to automatically triage the generic `RESTException`. It would help us if Iceberg could yield the `NoSuchWarehouseException` instead, so our application code can more confidently triage this runtime issue.
We expect other Iceberg users have similar operational workflows where distinguishing warehouse configuration errors from other failures would improve their incident response.
## Context
Split from #14965 per @danielcweeks's suggestion to discuss and vote on the spec change separately from the implementation.
See the dev list thread: https://lists.apache.org/thread/xshfmp6m78l4ys6loozwop0fjl0cov3d
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] Spec: Add 404 response for config endpoint [iceberg]
Posted by "rambleraptor (via GitHub)" <gi...@apache.org>.
rambleraptor commented on code in PR #15746:
URL: https://github.com/apache/iceberg/pull/15746#discussion_r3002627344
##########
open-api/rest-catalog-open-api.yaml:
##########
@@ -162,6 +162,8 @@ paths:
$ref: '#/components/responses/UnauthorizedResponse'
403:
$ref: '#/components/responses/ForbiddenResponse'
+ 404:
+ $ref: '#/components/responses/NoSuchWarehouseResponse'
Review Comment:
I don't think `204` is the proper way to go. The 4xx HTTP codes are meant to indicate client error. The client gave a warehouse that doesn't exist, which is a form of user error.
204 would mean that the warehouse exists and that the config has no data.
##########
open-api/rest-catalog-open-api.yaml:
##########
@@ -162,6 +162,8 @@ paths:
$ref: '#/components/responses/UnauthorizedResponse'
403:
$ref: '#/components/responses/ForbiddenResponse'
+ 404:
+ $ref: '#/components/responses/NoSuchWarehouseResponse'
Review Comment:
I don't think `204` is the proper way to go. The 4xx HTTP codes are meant to indicate client error. The client gave a warehouse that doesn't exist, which is a form of user error.
204 would mean that the warehouse exists and that the config has no parameters.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] SPEC: Add 404 response for /v1/config endpoint [iceberg]
Posted by "rdblue (via GitHub)" <gi...@apache.org>.
rdblue commented on code in PR #15746:
URL: https://github.com/apache/iceberg/pull/15746#discussion_r2990465467
##########
open-api/rest-catalog-open-api.yaml:
##########
@@ -162,6 +162,8 @@ paths:
$ref: '#/components/responses/UnauthorizedResponse'
403:
$ref: '#/components/responses/ForbiddenResponse'
+ 404:
+ $ref: '#/components/responses/NoSuchWarehouseResponse'
Review Comment:
I agree with @danielcweeks that we need a way to distinguish what wasn't found, although I don't see why this doesn't just use our normal error response with an example. Here is one you can copy:
```
404:
description: Not Found - Namespace provided in the `parent` query parameter is not found.
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
examples:
NoSuchNamespaceExample:
$ref: '#/components/examples/NoSuchNamespaceError' <--- Your error goes here
```
This doesn't require a new response object but does show how different missing objects can be represented.
I also wonder if this is the right response. Doesn't 404 typically mean that the resource identified by the path doesn't exist? But the config resource exists and the warehouse is just a parameter that the config resource is providing information for. I could be wrong, but I thought that 404 implied that the thing identified by the path doesn't exist, not that there was a problem finding information for a different (and optional) object.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] SPEC: Add 404 response for /v1/config endpoint [iceberg]
Posted by "oguzhanunlu (via GitHub)" <gi...@apache.org>.
oguzhanunlu commented on code in PR #15746:
URL: https://github.com/apache/iceberg/pull/15746#discussion_r2988198042
##########
open-api/rest-catalog-open-api.yaml:
##########
@@ -162,6 +162,8 @@ paths:
$ref: '#/components/responses/UnauthorizedResponse'
403:
$ref: '#/components/responses/ForbiddenResponse'
+ 404:
+ $ref: '#/components/responses/NoSuchWarehouseResponse'
Review Comment:
Thank you both for the feedback, let me share my view on both points.
@kevinjqliu That is an example from the Snowflake payload and I'd prefer `NotFoundResponse` to align with naming convention in the spec. However, I realized that 404 responses are inlined in all endpoints and named responses are used for status codes that mean the same thing across endpoints e.g. 400, 401, 403. It makes sense because what's `not found` is endpoint-dependent (namespace, table, view etc.) hence I think `/v1/config` 404 response should be inlined as well instead of adding e.g. `NotFoundResponse`. Would you agree?
@rambleraptor , @danielcweeks [raised](https://github.com/apache/iceberg/pull/14965#issuecomment-3747136540) a valid concern in the original PR #14965: 404 from config endpoint is ambiguous. It could mean "warehouse not found" or "misconfigured URL pointing to a non-Iceberg server". If clients only check HTTP status code, they can't distinguish the two. How would you suggest handling that? e.g. PlanErrorHandler checks error type to decide which exception to throw.
Looking forward to hearing what you think.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] SPEC: Add 404 response for /v1/config endpoint [iceberg]
Posted by "oguzhanunlu (via GitHub)" <gi...@apache.org>.
oguzhanunlu commented on PR #15746:
URL: https://github.com/apache/iceberg/pull/15746#issuecomment-4117504966
Thanks @kevinjqliu , I cleared the PR to have the spec change only and started a devlist thread at https://lists.apache.org/thread/07t5rfcxn3bbbpp75fkr2h1mwdp2o4mn with justification.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] SPEC: Add 404 response for /v1/config endpoint [iceberg]
Posted by "oguzhanunlu (via GitHub)" <gi...@apache.org>.
oguzhanunlu commented on code in PR #15746:
URL: https://github.com/apache/iceberg/pull/15746#discussion_r2991090880
##########
open-api/rest-catalog-open-api.yaml:
##########
@@ -162,6 +162,8 @@ paths:
$ref: '#/components/responses/UnauthorizedResponse'
403:
$ref: '#/components/responses/ForbiddenResponse'
+ 404:
+ $ref: '#/components/responses/NoSuchWarehouseResponse'
Review Comment:
@rdblue Thanks for the feedback. I've pushed a new commit to follow the inline pattern you shared.
On status code choice, let me share that Apache Polaris [throws](https://github.com/apache/polaris/blob/main/runtime/service/src/main/java/org/apache/polaris/service/catalog/iceberg/IcebergCatalogHandler.java#L1360) `NotFoundException` which gets [mapped](https://github.com/apache/polaris/blob/main/runtime/service/src/main/java/org/apache/polaris/service/exception/IcebergExceptionMapper.java#L174) to 404 when the warehouse doesn't exist.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] SPEC: Add 404 response for /v1/config endpoint [iceberg]
Posted by "rambleraptor (via GitHub)" <gi...@apache.org>.
rambleraptor commented on code in PR #15746:
URL: https://github.com/apache/iceberg/pull/15746#discussion_r2983192006
##########
open-api/rest-catalog-open-api.yaml:
##########
@@ -162,6 +162,8 @@ paths:
$ref: '#/components/responses/UnauthorizedResponse'
403:
$ref: '#/components/responses/ForbiddenResponse'
+ 404:
+ $ref: '#/components/responses/NoSuchWarehouseResponse'
Review Comment:
I'm personally a fan of not adding new response types.
We expect tools/libraries to be checking against the HTTP status codes when response parsing. But, if they're checking against the type, then those tools need to be updated to understand this new WarehouseNotFound exception.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] Spec: Add 404 response for config endpoint [iceberg]
Posted by "oguzhanunlu (via GitHub)" <gi...@apache.org>.
oguzhanunlu commented on PR #15746:
URL: https://github.com/apache/iceberg/pull/15746#issuecomment-4255913411
Thanks @kevinjqliu and everyone else who took time to look at this PR!
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] Spec: Add 404 response for config endpoint [iceberg]
Posted by "kevinjqliu (via GitHub)" <gi...@apache.org>.
kevinjqliu commented on PR #15746:
URL: https://github.com/apache/iceberg/pull/15746#issuecomment-4255833747
Thanks again @oguzhanunlu
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] Spec: Add 404 response for config endpoint [iceberg]
Posted by "kevinjqliu (via GitHub)" <gi...@apache.org>.
kevinjqliu merged PR #15746:
URL: https://github.com/apache/iceberg/pull/15746
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] Spec: Add 404 response for config endpoint [iceberg]
Posted by "stevenzwu (via GitHub)" <gi...@apache.org>.
stevenzwu commented on code in PR #15746:
URL: https://github.com/apache/iceberg/pull/15746#discussion_r2997643966
##########
open-api/rest-catalog-open-api.yaml:
##########
@@ -162,6 +162,8 @@ paths:
$ref: '#/components/responses/UnauthorizedResponse'
403:
$ref: '#/components/responses/ForbiddenResponse'
+ 404:
+ $ref: '#/components/responses/NoSuchWarehouseResponse'
Review Comment:
I also think 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 does exist, 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.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] API, OpenAPI: Add 404 response for /v1/config endpoint [iceberg]
Posted by "kevinjqliu (via GitHub)" <gi...@apache.org>.
kevinjqliu commented on code in PR #15746:
URL: https://github.com/apache/iceberg/pull/15746#discussion_r2978822534
##########
api/src/main/java/org/apache/iceberg/exceptions/NoSuchWarehouseException.java:
##########
Review Comment:
remove this too
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] SPEC: Add 404 response for /v1/config endpoint [iceberg]
Posted by "oguzhanunlu (via GitHub)" <gi...@apache.org>.
oguzhanunlu commented on code in PR #15746:
URL: https://github.com/apache/iceberg/pull/15746#discussion_r2988198042
##########
open-api/rest-catalog-open-api.yaml:
##########
@@ -162,6 +162,8 @@ paths:
$ref: '#/components/responses/UnauthorizedResponse'
403:
$ref: '#/components/responses/ForbiddenResponse'
+ 404:
+ $ref: '#/components/responses/NoSuchWarehouseResponse'
Review Comment:
Thank you both for the feedback, let me share my view on both points.
@kevinjqliu That is an example from the Snowflake payload and I'd prefer `NotFoundResponse` to align with naming convention in the spec. However, I realized that 404 responses are inlined in all endpoints and named responses are used for status codes that mean the same thing across endpoints e.g. 400, 401, 403. It makes sense because what's `not found` is endpoint-dependent (namespace, table, view etc.) hence I think `/v1/config` 404 response should be inlined as well. Would you agree?
@rambleraptor , @danielcweeks [raised](https://github.com/apache/iceberg/pull/14965#issuecomment-3747136540) a valid concern in the original PR #14965: 404 from config endpoint is ambiguous. It could mean "warehouse not found" or "misconfigured URL pointing to a non-Iceberg server". If clients only check HTTP status code, they can't distinguish the two. How would you suggest handling that? e.g. PlanErrorHandler checks error type to decide which exception to throw.
Looking forward to hearing what you think.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] SPEC: Add 404 response for /v1/config endpoint [iceberg]
Posted by "kevinjqliu (via GitHub)" <gi...@apache.org>.
kevinjqliu commented on code in PR #15746:
URL: https://github.com/apache/iceberg/pull/15746#discussion_r2982483320
##########
open-api/rest-catalog-open-api.yaml:
##########
@@ -162,6 +162,8 @@ paths:
$ref: '#/components/responses/UnauthorizedResponse'
403:
$ref: '#/components/responses/ForbiddenResponse'
+ 404:
+ $ref: '#/components/responses/NoSuchWarehouseResponse'
Review Comment:
both PR and devlist thread mentions `NotFoundException`, should we change it to that?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] Spec: Add 404 response for config endpoint [iceberg]
Posted by "stevenzwu (via GitHub)" <gi...@apache.org>.
stevenzwu commented on code in PR #15746:
URL: https://github.com/apache/iceberg/pull/15746#discussion_r2997643966
##########
open-api/rest-catalog-open-api.yaml:
##########
@@ -162,6 +162,8 @@ paths:
$ref: '#/components/responses/UnauthorizedResponse'
403:
$ref: '#/components/responses/ForbiddenResponse'
+ 404:
+ $ref: '#/components/responses/NoSuchWarehouseResponse'
Review Comment:
I also think 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 does exist, 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.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org