openapi: deal with error return types

[ahl]

We may do this in several PRs, but the end state should be that the various error types are well-captured for each endpoint. This will likely require us to think more carefully about the specific return types we want to expose to developers, the appropriate granularity, and the types of remediation we expect developers to take in the case of failures.

There are types of failures where we have more information:

• we could provide detailed information about input validation failures
• we could provide specific guidance about retries in the case of 503 (service unavailable)
• etc.

Ideally we should make use of the components/responses field of OpenAPI to minimize the number of times these shared error structures are represented in the OpenAPI document.

[WasabiFan]

Would it be correct to say that currently there is no way to output errors in the responses section of an endpoint's OpenAPI doc? (Even manually, barring postprocessing of the JSON structure.) Currently, it looks like only one possible response can be modeled in the registered routes.