Extend response/error with item and reuse it for all the errors

[googleson78]

From looking at response/error_*.yaml, it seems like pretty much all the errors have the fields of response/error.yaml, as well as an additional item field, which is left opaque to be extended in different endpoints. Could we not instead have a response/error_with_item.yaml which has the response/error.yaml fields + an item field, and reuse that for all the errors in different endpoints, so that there are not many different error types which are actually practically identical? It seems to me that this would be an easier way to organise things

[googleson78]

Actually, this is not only a matter of convenience, but somewhat a matter of correctness.

Currently, this spec for the Agency api (references/agency.yaml):

paths:
  /telemetry:
    post:
      responses:
        "400":
          description: Bad request.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: ../models/response/bulk.yaml
                  - required:
                      - failures
                    properties:
                      failures:
                        minItems: 1
                        items:
                          properties:
                            item:
                              $ref: ../models/telemetry.yaml
                          oneOf:
                            - $ref: ../models/response/error_bad_param.yaml
                            - $ref: ../models/response/error_missing_param.yaml

is misleading. It specifies a oneOf describing two alternatives which the error format might take, but the two errors are structurally the same, so it doesn't really matter which one we specify. Not only does it not matter which one is specified, but it is also impossible to distinguish between them. Consider

{
  "item": <someTelemetry>,
  "error": "bla",
  "error_description": "bla",
  "error_details": ["bla"]
}

Is this a error_bad_param.yaml or is this a error_missing_param.yaml? It seems to me that it could be both.