Error responses in CAMARA_common.yaml have limited reusability

[rartych]

Problem description
As indicated in #662 directly referencing error responses from CAMARA_common.yaml can result in incorrect defnitions within API specifications. Initially, the CAMARA_common.yaml file was intended to serve as a source for copying text chunks rather than providing fully usable schema definitions for errors.

Each Generic4xx response object in CAMARA_common.yaml currently bundles two distinct components:

• Schema: Contains allOf with status/code enums. These schemas often need to be API-specific (individual APIs extend the enums for specific codes and exlude irrelevant codes).
• Examples: Provides illustrative static values for each error code. These examples are invariant across all APIs that utilize the corresponding error codes.

To avoid inconsistencies any response with API-customizable codes can not be $ref'ed to CAMARA_common.yaml response.

Expected behavior

1. Add a components/examples section to CAMARA_common.yaml and move all GENERIC_xxx_CODE example objects to this section.
2. API specifications should define their full local response structure based on ErrorInfo schema and cherry-pick reusable examples via $ref. API-specific examples may be added locally.
3. The Generic4xx response objects can be relocated to API template artifacts for better clarity.

Alternative solution

1. Add a components/examples section to CAMARA_common.yaml and move all GENERIC_xxx_CODE example objects to this section (similar to the expected behavior p.1 and 2).
2. Split response components based on invariance:
   • Keep fully-reusable, most common ones in CAMARA_common.yaml to be referenced directly.
   • Relocate variable, API-specific response templates to API template artifacts for customization.

Additional context
Current API templates artifacts may need to be updated to follow the choosen solution.

[PedroDiez]

Good point to be raised.

In our view during Sync26 M3, M4 we can give flexibility to API initiatives to perform a mix between local definitions of Error responses and references to local CAMARA_common.yaml when they can be reused and think in a long-term solution for Signal27.

The point of "conflict" happens for HTTP statuses that can have more than one "code".

[PedroDiez]

From technical perspective, here it is provided some initial input:

• The problem arises in error scenarios where a single HTTP status code can be associated with more than one error code.
  • The definitions for 401, 405, 406, 410, 412, 415, 500, 501, 502, 503, and 504 are single-code (and should remain so), making them fully reusable.
  • "Conflict" scenarios happens with 400, 403, 404, 409, 422 and 429.

With former comment in mind, we foresee two options from the beginning:

• Option 1: Basically the one indicated in Expected behaviour. As per our understanding that means becoming only normative the Error Info Model: https://github.com/camaraproject/Commonalities/blob/main/artifacts/common/CAMARA_common.yaml#L110. And within the API initiative make the adjustment indicating the applicable codes

Example:

"404":
  description: Not found
  headers:
    x-correlator:
      $ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator"
  content:
    application/json:
      schema:
        allOf:
          - $ref: "../common/CAMARA_common.yaml#/components/schemas/ErrorInfo"
          - type: object
            properties:
              status:
                enum:
                  - 404
              code:
                enum:
                  - NOT_FOUND
                  - IDENTIFIER_NOT_FOUND
      examples:
        GENERIC_404_NOT_FOUND:
          value:
            status: 404
            code: NOT_FOUND
            message: The specified resource is not found.
        GENERIC_404_IDENTIFIER_NOT_FOUND:
          value:
            status: 404
            code: IDENTIFIER_NOT_FOUND
            message: Device identifier not found.

PROs:
- Minimum or None Commonalities CAMARA_common.yaml maintenance with regards on this.

CONS:
- May (recommended) require improvements in linter workflows to enforce that the codes indicated are between the ones allowed for that HTTP status (as a check to avoid undesired typos)

• Option 2: Define in CAMARA_Common.yaml every combination HTTP status - code. In this way, in CAMARA_common.yaml is hosted the normative definition of every error scenario. This way increases the ratio of reusability of CAMARA_common.yaml in API error definitions
  • Completely in the cases of 401, 405, 406, 410, 412, 415, 500, 501, 502, 503, and 504 (single-code cases)
  • In many cases where API specification only consumes a single-code from 400, 403, 404, 409, 422 and 429

When multiple codes are consumed, they can be detailed as per Option 1 or even as shown in below example:

"404":
  description: Not found
  headers:
    x-correlator:
      $ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator"
  content:
    application/json:
      schema:
        oneOf:
          - allOf:
              - $ref: "../common/CAMARA_common.yaml#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum:
                      - 404
                  code:
                    enum:
                      - NOT_FOUND
          - allOf:
              - $ref: "../common/CAMARA_common.yaml#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum: 
                      - 404
                  code:
                    enum: 
                      - IDENTIFIER_NOT_FOUND
      examples:
        GENERIC_404_NOT_FOUND:
          value:
            status: 404
            code: NOT_FOUND
            message: The specified resource is not found.
        GENERIC_404_IDENTIFIER_NOT_FOUND:
          value:
            status: 404
            code: IDENTIFIER_NOT_FOUND
            message: Device identifier not found.

PROs:
- Low CAMARA_common.yaml maintenance with regards on this. Only to add a new HTTP status - code combination when defined or remove when deprecated. Not expected to happen so much.

CONS:
- May require improvements in API spec bundling depending the way selected to cover scenarios where in an API endpoint several codes associated to the same HTTP status may occur.

From TEF side we think Option 3 can provide benefits as increasing reusability of error scenarios defined in CAMARA_common.yaml

[hdamker]

Let me add an "Option 3" proposal: 10+7 minimal reference-able error responses covering about 80% of cases + reusable examples to build local error responses (covering the 20% cases where API specific codes are involved).

Rationale

The Generic4xx/5xx responses in CAMARA_common.yaml bundle universal error codes with codes that apply only to specific API categories. Under the 0.8.0 direct-referencing model, every API that references such a response declares error codes it can never return; #662 (403 INVALID_TOKEN_CONTEXT) is the acute case, but not the only one.

To put the redesign on an evidence basis, I analyzed the error responses declared in the latest release of every CAMARA API repository (53 repositories with releases, 85 API definition files):

• 400/403 are declared by 100% of the API definitions, 401/404 by 96%, 422 by 75%, 429 by 56%, 409 by 34%, 410 by 32% (nearly always in notification callbacks). 405, 406, 412 and 502 are declared by no released API, 415/504 by one each — matching the Design Guide rule that these statuses are not documented by default.
• Where API teams deviated from the template enums (a deliberate choice), they overwhelmingly chose minimal sets: {PERMISSION_DENIED} alone (53 files), {INVALID_ARGUMENT} alone (36), TOO_MANY_REQUESTS without QUOTA_EXCEEDED (every deliberate 429 choice).
• 51% of the declared error responses are verbatim copies of the template enums — more than 20 APIs still carry 403 INVALID_TOKEN_CONTEXT — i.e. template inertia, not actual need.
• The 422 identifier codes split cleanly by how the API identifies its subject: device-identified APIs declare all four identifier codes, phone-number-identified APIs declare three (UNSUPPORTED_IDENTIFIER does not apply to a single identifier type).
• No released API references the CAMARA_common.yaml responses via external $ref yet — all released definitions hold local copies. The window to restructure without breaking released references is open, but it closes as 0.8.0 adoption progresses.

Proposed responses in CAMARA_common.yaml

Replace the Generic* template responses with minimal, directly referenceable responses. Each contains only codes every referencing API can return:

Name	Codes
BadRequest400	INVALID_ARGUMENT
BadRequestWithRange400	INVALID_ARGUMENT, OUT_OF_RANGE
Unauthenticated401	UNAUTHENTICATED
PermissionDenied403	PERMISSION_DENIED
NotFound404	NOT_FOUND
IdentifierNotFound404	IDENTIFIER_NOT_FOUND
AlreadyExists409	ALREADY_EXISTS
PhoneNumberIdentifier422	MISSING_IDENTIFIER, UNNECESSARY_IDENTIFIER, SERVICE_NOT_APPLICABLE
DeviceIdentifier422	same + UNSUPPORTED_IDENTIFIER
TooManyRequests429	TOO_MANY_REQUESTS

Statuses that are not documented by default (405, 406, 412, 415, 5xx) get no referenceable response — their generic examples remain available (see below) for the APIs with a justified use case.

Proposed responses in CAMARA_event_common.yaml

Subscription-specific error responses stay in CAMARA_event_common.yaml (as in 0.8.0), extended to:

Name	Codes
CreateSubscriptionBadRequest400	as in 0.8.0
SubscriptionIdRequired400	as in 0.8.0
SubscriptionPermissionDenied403	as in 0.8.0
CreateSubscriptionConflict409 (new)	ABORTED, ALREADY_EXISTS
SinkGone410 (new)	GONE — replaces Generic410; used in notification callbacks
CreateSubscriptionDevice422 (new)	device identifier codes + MULTIEVENT_SUBSCRIPTION_NOT_SUPPORTED, MULTIEVENT_COMBINATION_TEMPORARILY_NOT_SUPPORTED, PRIVATE_KEY_JWT_NOT_CONFIGURED
CreateSubscriptionPhoneNumber422 (new)	phone-number identifier codes + the same three

CreateSubscriptionUnprocessableEntity422 is deprecated: it bundles the device identifier codes for all subject types, which repeats the superset pattern.

Examples as reusable components

• New components/examples section in CAMARA_common.yaml holding the generic error examples — including those of codes without a referenceable response (QUOTA_EXCEEDED, INCOMPATIBLE_STATE, ABORTED, 5xx, 405/406/412/415). Component names keep the established example keys (GENERIC_<STATUS>_<CODE>).
• The common responses reference these examples (CAMARA_event_common.yaml references them cross-file, removing today's duplication between the two files).
• APIs that need API-specific codes define the response locally, selecting exactly the codes they return and referencing the shared examples — so example wording stays consistent even in API-specific responses. The API templates will demonstrate this pattern.
• The identifier-code examples come in two wording variants (device / phone number), so the messages finally match the subject type; examples shared by both subject types get subject-neutral wording.
• Each status gets a short intro comment in the file: which referenceable response(s) exist and which examples are available for local definitions.

A coverage check against the released APIs: 71% of the deliberately chosen error declarations match one of the proposed responses exactly; 21% contain API-specific codes and are correctly served by local definitions referencing the shared examples; the remaining 6% are mostly residues of pre-r3.2 enums that disappear with realignment.

Migration

• Target: Commonalities 0.9.0 within the current meta-release cycle. Response component names are internal references, not visible to API consumers — APIs at release-candidate stage can adopt the new names without breaking their contract, and already-released release candidates pin r4.3 and remain valid.
• The GenericXXX responses (and CreateSubscriptionUnprocessableEntity422) stay in place as deprecated, content-frozen, with a note pointing to their replacements — existing valid definitions can migrate, they don't have to. Two exceptions, both bug fixes independent of the restructuring: INVALID_TOKEN_CONTEXT is removed from Generic403 (Make INVALID_TOKEN_CONTEXT opt-in in the shared Generic403 #662), and the deprecated 409 code CONFLICT is removed (enum and example).
• Removal of the deprecated responses in the next meta-release cycle, accompanied by validation rules (warning on deprecated-response usage, enum/example consistency) — advisory first.