Resolve linter warnings

[janbuchar]

In the current state, the openapi linter reports ~150 warnings, which is way more that what we should have. After the structure of the spec is cleaned up, we should look into that.

Many will be resolved just by specifying what 4xx errors look like throughout the API.