API, Core: Add 404 handling for /v1/config endpoint

[oguzhanunlu]

Summary

This PR proposes adding HTTP 404 as a documented response for the /v1/config endpoint in the REST Catalog OpenAPI specification.

• The OpenAPI spec is amended to allow 404 (Not Found) if a warehouse does not exist
• The core Java library is amended to raise a NoSuchWarehouseException corresponding to this error response
• Unit test to assert 404 response yield the expected exception in the Java core library

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:

{
  "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.

See the corresponding devlist thread at https://lists.apache.org/thread/xshfmp6m78l4ys6loozwop0fjl0cov3d

[kevinjqliu]

Thanks for raising a corresponding devlist thread, could you include it in the PR description? https://lists.apache.org/thread/xshfmp6m78l4ys6loozwop0fjl0cov3d

I'll chime in on the thread 😄

[oguzhanunlu]

Thanks @kevinjqliu ! I just updated PR description, at the bottom, to refer to the devlist thread.

[kevinjqliu]

Suggested change

	# Note that this is a representative example response for use as a shorthand in the spec.
	# The fields `message` and `type` as indicated here are not presently prescriptive.

nit: dont really need this explanation since its under example

[danielcweeks]

@oguzhanunlu I'm a little concerned around the semantics for a 404 on the config endpoint. The config endpoint doesn't specifically identify a warehouse, it the configuration endpoint for a REST Catalog server, so a 404 could also indicate that the url is incorrectly defined and the config endpoint is not available at the requested path.

This could result in confusing errors if we aren't handling that correctly. You should add some tests that return a 404 that is not formatted as an error response and ensure that we're surfacing an appropriate error.

[oguzhanunlu]

Thanks for the feedback @danielcweeks. You're right that a 404 on /v1/config could come from either:

1. A valid Iceberg server (warehouse doesn't exist)
2. A misconfigured URL pointing to a non-Iceberg server

I traced through the error handling flow and have two options:

Option 1: Check error.type() != null

When DefaultErrorHandler.parseResponse() fails to parse the response body, it returns an ErrorResponse with type = null. Per the spec, type is required, so valid Iceberg servers must include it.

if (error.code() == 404 && error.type() != null) {
  throw new NoSuchWarehouseException("%s", error.message());
}

Pros: Minimal change
Cons: Uses type as a proxy for "did parsing succeed?" - relies on the fallback not setting type, which is an implementation detail rather than intentional design

Option 2: Add explicit hasValidBody flag to ErrorResponse

Add a boolean field that explicitly tracks whether the response body was successfully parsed.

Pros: Explicit, self-documenting, won't break if fallback logic changes
Cons: Larger change - requires modifying ErrorResponse, parser, and fallback logic

Which approach would you prefer?

[oguzhanunlu]

Hi @danielcweeks, I've addressed your feedback by adding a null check for error.type() to distinguish valid Iceberg 404 responses from 404s caused by misconfigured URIs.

When the URI points to a non-Iceberg server, the response won't have a valid error type, so we fall through to the default handler instead of throwing NoSuchWarehouseException.

I've also added a test for the misconfigured URI case and removed the comment per @kevinjqliu's suggestion.

I'd appreciate another look when you have a chance!