Expand error-response coverage for 406, signatures, /token 404, and 400/204 cleanup

[Mehrn0ush]

Summary

Several documented HTTP outcomes cannot be expressed accurately with the current error-response model. unknown-error-type only allows OBJECT_UNKNOWN and OBJECT_NOT_SHAREABLE, but download flows also need to signal “no matching format” and “no signature,” /token documents an unimplemented-endpoint 404 that OpenAPI does not declare, generic 400 bodies are unspecified, and an unused body-bearing 204 component remains in the spec.

#270 improves concealment (403 vs concealing 404) but does not close these gaps. This issue tracks the remaining error-coverage work as a follow-up after #270 merges.

Current gaps

1. 406 cannot name “format unavailable”

Download operations declare 406 via 406-no-acceptable-format, whose body is error-response → unknown-error-type. That enum only has:

• OBJECT_UNKNOWN
• OBJECT_NOT_SHAREABLE

Neither means “the revision exists but no format matches mediaType / Accept.”

2. Missing signature uses a generic 404

Artifact signature download prose returns 404 when the selected format has no published signature, but the response is the same 404-object-by-id-not-found / object-unknown path used for missing resources. Clients cannot distinguish “artifact unknown” from “signature not published.”

3. /token 404 is documented but not in OpenAPI

/token description says a 404 means the endpoint is not implemented (open / no-auth servers). Declared responses are only 200 / 400 / 401. The operation table in published docs therefore omits a documented outcome.

4. Generic 400 body is unspecified

400-invalid-request uses application/json: {} with no schema. Either define a common structured body, or state explicitly that clients must not depend on 400 contents (token errors already have token-error-response).

5. Unused 204-common-delete

components.responses.204-common-delete declares JSON content on a bodyless 204, and nothing $refs it. It should be removed or corrected if delete is ever in scope.

Proposed direction

• Extend unknown-error-type (or split error enums by context) with distinct codes such as:
  • NO_ACCEPTABLE_FORMAT for 406
  • SIGNATURE_NOT_FOUND for signature-absent 404
• Keep concealment semantics from Align OpenAPI security with open and mixed TEA servers #270: concealing 404 remains OBJECT_UNKNOWN / not-shareable as already described there — do not overload those for format/signature cases.
• Declare 404 on /token with a clear description (not implemented), distinct from resource 404-object-by-id-not-found.
• For resource 400-invalid-request: either a small shared schema or an explicit “body not interoperable / do not depend on contents” rule.
• Remove unused 204-common-delete (or fix it if retained).

Relation to other work

• Align OpenAPI security with open and mixed TEA servers #270 / Align OpenAPI security with open and mixed TEA servers #269: concealment and 401/403 — prerequisite; land first, then implement this.
• 404 clarification #274: discovery 404 overload (TEI unknown vs endpoint missing) — related theme, separate issue; this issue is about OpenAPI error bodies and download//token coverage.
• Align /token responses with RFC 6749 cache and Basic encoding #272 / Defer RFC 8693 token exchange for TEA 1.0 #277: token cache/encoding and RFC 8693 deferral — do not cover these gaps.

Out of scope

• Redesigning pagination 400 semantics beyond stating body policy
• Publisher/delete API surface (unless 204-common-delete is intentionally revived)
• CLE or discovery cardinality response shape

If this direction looks right I'll make a PR after #270 merge?

[taleodor]

Direction is right, and all five gaps check out against main: the 406 body can only say OBJECT_UNKNOWN or OBJECT_NOT_SHAREABLE; the signature download prose returns the same 404 for "revision unknown" and "no signature published"; /token declares only 200 / 400 / 401 while its description promises a 404; 400-invalid-request is application/json: {}; and 204-common-delete has zero references (the only unused response component in the file).

Adjustments before the PR:

1. The /token 404 must not require a TEA body. The point of that 404 is that the endpoint may not exist at all, in which case the web server answers with whatever it answers. Declaring it with an error-response body would make a server that honestly does not implement /token non-conforming. Declare 404 on /token with no content requirement and the description "not implemented; the body, if any, carries no meaning", which is what the discovery document already says since fix: clean up post-merge discovery 404 and checksum leftovers #297.

2. Keep one enum, extend it. Do not split error enums by context: a TEA error is a JSON object with a string error (fix: clean up post-merge discovery 404 and checksum leftovers #297), and clients tolerate values they do not know, so one enum keeps that rule simple.

3. Coordinate with CLE in OpenAPI vs ECMA-428 CLE 1.0.0 — align or name a TEA projection? #278. That issue adds NOT_IMPLEMENTED to the same enum for the CLE endpoints. Land all enum additions in one PR or the two will conflict.

4. Concealment needs one sentence. SIGNATURE_NOT_FOUND and NO_ACCEPTABLE_FORMAT both reveal that the artifact exists. Fine for a client that has passed authorization, but a server concealing an object from a client shall answer OBJECT_UNKNOWN for every sub-resource of it, signatures and formats included. Otherwise Align OpenAPI security with open and mixed TEA servers #270's concealment leaks through the download endpoints.

5. 401 and 403 have the same empty {} body as 400. Whatever is decided for 400 should apply to all three. I prefer the shared schema over a "do not depend on it" rule: "any 4xx from a resource endpoint may carry an error-response body; when present, error is from the enum; clients shall not require a body", plus INVALID_REQUEST in the enum. The 401 challenge header stays the primary signal, as today.

6. INVALID_PAGE_TOKEN. The 400 description already spends three lines on bad page tokens; a dedicated value lets a client restart pagination without parsing prose. One enum line in the same PR.

7. Remove 204-common-delete; nothing references it and delete is out of scope.

On 406 itself: RFC 9110 defines it for Accept negotiation, and using it when an explicit mediaType names a missing format is a stretch. The spec already does this on four operations and the body code removes the ambiguity, so not reopening that here.