Problem description
The shared Generic403 in artifacts/common/CAMARA_common.yaml lists INVALID_TOKEN_CONTEXT as an active enum value with a GENERIC_403_INVALID_TOKEN_CONTEXT example. Per #369 and the API Design Guide §6.1, this code applies only to APIs whose scope is to confirm whether a supplied identity matches the one bound to the three-legged access token (e.g. KYC-Match).
As part of the shared Generic403, every API that $refs it inherits the code and declares a 403 INVALID_TOKEN_CONTEXT it will never legitimately return. Under the 0.8.0 direct-$ref model this is now the default for all referencing APIs.
Expected behavior
Comment out INVALID_TOKEN_CONTEXT in Generic403 — both the enum entry and the example — making it opt-in, matching the {{SPECIFIC_CODE}} precedent already in the same block. Confirm-the-match APIs add the code to their own Generic403. Comments are dropped at bundling, so $ref resolution and bundled artifacts stay clean.
Alternative
Leave the shared Generic403 as is. Then every API that should not return INVALID_TOKEN_CONTEXT must define its own local Generic403 and cannot $ref the common one. That makes the shared Generic403 unusable for the majority of APIs and pushes a local 403 definition into nearly every spec — the opposite of the direct-$ref consolidation that 0.8.0 encourages.
Additional context
Scoping background: #259, #369, #321. The Design Guide §6.1 already restricts the code to confirm-the-match scopes; this aligns the shared Generic403 with that rule.
The same opt-in question applies to other non-universal codes in the shared error responses (e.g. IDENTIFIER_NOT_FOUND in Generic404, the identifier codes in Generic422, GONE in Generic410); and CONFLICT in Generic409 is marked deprecated but still listed. Those are worth a separate review and are out of scope here.
Problem description
The shared
Generic403inartifacts/common/CAMARA_common.yamllistsINVALID_TOKEN_CONTEXTas an active enum value with aGENERIC_403_INVALID_TOKEN_CONTEXTexample. Per #369 and the API Design Guide §6.1, this code applies only to APIs whose scope is to confirm whether a supplied identity matches the one bound to the three-legged access token (e.g. KYC-Match).As part of the shared
Generic403, every API that$refs it inherits the code and declares a403 INVALID_TOKEN_CONTEXTit will never legitimately return. Under the 0.8.0 direct-$refmodel this is now the default for all referencing APIs.Expected behavior
Comment out
INVALID_TOKEN_CONTEXTinGeneric403— both the enum entry and the example — making it opt-in, matching the{{SPECIFIC_CODE}}precedent already in the same block. Confirm-the-match APIs add the code to their ownGeneric403. Comments are dropped at bundling, so$refresolution and bundled artifacts stay clean.Alternative
Leave the shared
Generic403as is. Then every API that should not returnINVALID_TOKEN_CONTEXTmust define its own localGeneric403and cannot$refthe common one. That makes the sharedGeneric403unusable for the majority of APIs and pushes a local 403 definition into nearly every spec — the opposite of the direct-$refconsolidation that 0.8.0 encourages.Additional context
Scoping background: #259, #369, #321. The Design Guide §6.1 already restricts the code to confirm-the-match scopes; this aligns the shared
Generic403with that rule.The same opt-in question applies to other non-universal codes in the shared error responses (e.g.
IDENTIFIER_NOT_FOUNDinGeneric404, the identifier codes inGeneric422,GONEinGeneric410); andCONFLICTinGeneric409is marked deprecated but still listed. Those are worth a separate review and are out of scope here.