CAMARA_common.yaml

info:
  title: CAMARA common data types
  description: |
    Common data types for CAMARA APIs.
    This file contains Commonalities-owned schemas that are identical across all
    CAMARA APIs, including error responses, common parameters, headers, and
    reusable data types.

    API repositories place this file in `code/common/` and reference schemas
    via `$ref: "../common/CAMARA_common.yaml#/components/schemas/<SchemaName>"`,
    and error responses and examples via the corresponding
    `#/components/responses/...` and `#/components/examples/...` pointers.
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  version: wip
  x-camara-commonalities: wip

components:
  securitySchemes:
    openId:
      type: openIdConnect
      openIdConnectUrl: https://example.com/.well-known/openid-configuration
      description: OpenID Connect authentication via discovery metadata.

  headers:
    x-correlator:
      description: Correlation id for the different services
      schema:
        $ref: "#/components/schemas/XCorrelator"

    x-total-count:
      description: Total number of items. Mirrors `pagination.totalCount` in the response body.
      required: false
      schema:
        $ref: "#/components/schemas/TotalCount"

    x-total-pages:
      description: Total number of pages. Mirrors `pagination.totalPages` in the response body.
      required: false
      schema:
        $ref: "#/components/schemas/TotalPages"

    link:
      description: |
        Navigation links for paginated results following
        [RFC 8288](https://www.rfc-editor.org/rfc/rfc8288).
        Includes only the rels applicable to the current position
        (`first`, `prev`, `next`, `last`). All original query parameters
        are preserved in Link URLs.
        Example:
          Link: <https://api.example.com/v1/resources?page=1&perPage=20>; rel="first",
                <https://api.example.com/v1/resources?page=2&perPage=20>; rel="prev",
                <https://api.example.com/v1/resources?page=4&perPage=20>; rel="next",
                <https://api.example.com/v1/resources?page=5&perPage=20>; rel="last"
      required: false
      schema:
        type: string
        maxLength: 8192

  parameters:
    x-correlator:
      name: x-correlator
      in: header
      description: Correlation id for the different services
      schema:
        $ref: "#/components/schemas/XCorrelator"

    page:
      name: page
      in: query
      description: >
        Requested page number. Pages are 1-indexed.
        Values below 1 are rejected with `400 INVALID_ARGUMENT`.
      required: false
      schema:
        $ref: "#/components/schemas/Page"

    perPage:
      name: perPage
      in: query
      description: >
        Number of resources to return per page.
        Values outside the allowed range are rejected with `400 INVALID_ARGUMENT`.
      required: false
      schema:
        $ref: "#/components/schemas/PerPage"

  schemas:
    XCorrelator:
      type: string
      description: Correlator string, UUID format recommended but any string matching the pattern can be used
      pattern: ^[a-zA-Z0-9-_:;.\/<>{}]{0,256}$
      maxLength: 256
      example: "b4333c46-49c0-4f62-80d7-f0ef930f1c46"

    Date:
      type: string
      description: The date, using [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) full-date format "YYYY-MM-DD"
      format: date
      minLength: 10
      maxLength: 10
      example: "2023-07-03"

    DateTime:
      type: string
      format: date-time
      maxLength: 64
      description: Timestamp. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone.
      example: "2018-04-05T17:31:00Z"
    TimePeriod:
      type: object
      description: A period of time defined by a start date and an optional end date. If `endDate` is not included, then the period has no ending date.
      properties:
        startDate:
          $ref: "#/components/schemas/DateTime"
        endDate:
          $ref: "#/components/schemas/DateTime"
      required:
        - startDate
    ErrorInfo:
      type: object
      description: A structured error response providing details about a failed request, including the HTTP status code, an error code, and a human-readable message
      required:
        - status
        - code
        - message
      properties:
        status:
          type: integer
          format: int32
          minimum: 100
          maximum: 599
          description: HTTP response status code
        code:
          type: string
          maxLength: 96
          description: A human-readable code to describe the error
        message:
          type: string
          maxLength: 512
          description: A human-readable description of what the event represents
    Device:
      description: |
        End-user equipment able to connect to a mobile network. Examples of devices include smartphones or IoT sensors/actuators.
            The developer can choose to provide the below specified device identifiers:
            * `ipv4Address`
            * `ipv6Address`
            * `phoneNumber`
            * `networkAccessIdentifier`
            NOTE1: the network operator might support only a subset of these options. The API Consumer can provide multiple identifiers to ensure compatibility across different network operators. In this case, the API Provider will use one of the identifiers for the API logic without performing any matching checks among the provided identifiers.
            NOTE2: as for this Commonalities release, we are enforcing that the networkAccessIdentifier is only part of the schema for future-proofing, and CAMARA does not currently allow its use. After the CAMARA meta-release work is concluded and the relevant issues are resolved, its use will need to be explicitly documented in the guidelines.
      type: object
      properties:
        phoneNumber:
          $ref: "#/components/schemas/PhoneNumber"
        networkAccessIdentifier:
          $ref: "#/components/schemas/NetworkAccessIdentifier"
        ipv4Address:
          $ref: "#/components/schemas/DeviceIpv4Address"
        ipv6Address:
          $ref: "#/components/schemas/DeviceIpv6Address"
      minProperties: 1

    DeviceResponse:
      description: |
        An identifier for the end-user equipment able to connect to the network that the response refers to. This parameter is only returned when the API consumer includes the `device` parameter in their request (i.e. they are using a two-legged access token), and is relevant when more than one device identifier is specified, as only one of those device identifiers is allowed in the response.

        If the API consumer provides more than one device identifier in their request, and this schema is included in the response definition, the API provider MUST use it to return a single identifier which is the one they are using to fulfil the request, even if the identifiers do not match the same device. API provider does not perform any logic to validate/correlate that the indicated device identifiers match the same device. No error should be returned if the identifiers are otherwise valid to prevent API consumers correlating different identifiers with a given end user.

      allOf:
        - $ref: "#/components/schemas/Device"
        - maxProperties: 1

    PhoneNumber:
      description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'.
      type: string
      pattern: '^\+[1-9][0-9]{4,14}$'
      maxLength: 16
      example: "+123456789"

    NetworkAccessIdentifier:
      description: A public identifier addressing a subscription in a mobile network. In 3GPP terminology, it corresponds to the GPSI formatted with the External Identifier ({Local Identifier}@{Domain Identifier}). Unlike the telephone number, the network access identifier is not subjected to portability ruling in force, and is individually managed by each operator.
      type: string
      maxLength: 2048
      example: "123456789@example.com"

    DeviceIpv4Address:
      type: object
      description: |
        The device should be identified by either the public (observed) IP address and port as seen by the application server, or the private (local) and any public (observed) IP addresses in use by the device (this information can be obtained by various means, for example from some DNS servers).

        If the allocated and observed IP addresses are the same (i.e. NAT is not in use) then  the same address should be specified for both publicAddress and privateAddress.

        If NAT64 is in use, the device should be identified by its publicAddress and publicPort, or separately by its allocated IPv6 address (field ipv6Address of the Device object)

        In all cases, publicAddress must be specified, along with at least one of either privateAddress or publicPort, dependent upon which is known. In general, mobile devices cannot be identified by their public IPv4 address alone.
      properties:
        publicAddress:
          $ref: "#/components/schemas/SingleIpv4Address"
        privateAddress:
          $ref: "#/components/schemas/SingleIpv4Address"
        publicPort:
          $ref: "#/components/schemas/Port"
      anyOf:
        - required: [publicAddress, privateAddress]
        - required: [publicAddress, publicPort]
      example:
        publicAddress: "84.125.93.10"
        publicPort: 59765

    SingleIpv4Address:
      description: A single IPv4 address with no subnet mask
      type: string
      format: ipv4
      maxLength: 15
      example: "84.125.93.10"

    SingleIpv6Address:
      description: A single IPv6 address with no subnet mask
      type: string
      format: ipv6
      maxLength: 45
      example: "2001:db8:85a3:8d3:1319:8a2e:370:7344"

    Port:
      description: TCP or UDP port number
      type: integer
      format: int32
      minimum: 1
      maximum: 65535

    DeviceIpv6Address:
      description: |
        The device should be identified by the observed IPv6 address, or by any single IPv6 address from within the subnet allocated to the device (e.g. adding ::0 to the /64 prefix).
      allOf:
        - $ref: "#/components/schemas/SingleIpv6Address"

    Area:
      description: Base schema for all areas
      type: object
      properties:
        areaType:
          $ref: "#/components/schemas/AreaType"
      required:
        - areaType
      discriminator:
        propertyName: areaType
        mapping:
          CIRCLE: "#/components/schemas/Circle"
          POLYGON: "#/components/schemas/Polygon"

    AreaType:
      type: string
      description: |
        Type of this area.
        CIRCLE - The area is defined as a circle.
        POLYGON - The area is defined as a polygon.
      enum:
        - CIRCLE
        - POLYGON

    Circle:
      description: Circular area
      allOf:
        - $ref: "#/components/schemas/Area"
        - type: object
          required:
            - center
            - radius
          properties:
            center:
              $ref: "#/components/schemas/Point"
            radius:
              type: number
              description: Distance from the center in meters
              minimum: 1

    Polygon:
      description: Polygonal area. The Polygon should be a simple polygon, i.e. should not intersect itself.
      allOf:
        - $ref: "#/components/schemas/Area"
        - type: object
          required:
            - boundary
          properties:
            boundary:
              $ref: "#/components/schemas/PointList"

    PointList:
      description: List of points defining a polygon
      type: array
      items:
        $ref: "#/components/schemas/Point"
      minItems: 3
      maxItems: 15

    Point:
      type: object
      description: Coordinates (latitude, longitude) defining a location in a map
      required:
        - latitude
        - longitude
      properties:
        latitude:
          $ref: "#/components/schemas/Latitude"
        longitude:
          $ref: "#/components/schemas/Longitude"
      example:
        latitude: 50.735851
        longitude: 7.10066

    Latitude:
      description: Latitude component of a location
      type: number
      format: double
      minimum: -90
      maximum: 90

    Longitude:
      description: Longitude component of location
      type: number
      format: double
      minimum: -180
      maximum: 180

    # ─────────────────────────────────────────────────────────────────────────
    # Pagination
    # ─────────────────────────────────────────────────────────────────────────

    Pagination:
      description: Pagination details helping to navigate through paged results efficiently.
      type: object
      properties:
        page:
          $ref: "#/components/schemas/Page"
        perPage:
          $ref: "#/components/schemas/PerPage"
        totalCount:
          $ref: "#/components/schemas/TotalCount"
        totalPages:
          $ref: "#/components/schemas/TotalPages"

    Page:
      type: integer
      format: int32
      minimum: 1
      maximum: 2147483647
      default: 1
      description: Current page number (1-indexed).
      example: 1
    PerPage:
      type: integer
      format: int32
      minimum: 1
      maximum: 100
      default: 20
      description: Number of items per page.
      example: 20
    TotalCount:
      type: integer
      format: int32
      minimum: 0
      maximum: 2147483647
      description: Total number of items matching the query, after filters applied. MAY be omitted where a full count query is prohibitively expensive.
      example: 87
    TotalPages:
      type: integer
      format: int32
      minimum: 0
      maximum: 2147483647
      description: Total number of pages. Equals ceil(totalCount / perPage). MAY be omitted where totalCount is omitted.
      example: 5
  responses:
    # ─────────────────────────────────────────────────────────────────────────
    # CAMARA error responses — catalogue
    #
    # Minimal, directly referenceable error responses. Each response contains
    # only error codes that every referencing API can return. Subscription and
    # notification specific error responses are defined in
    # CAMARA_event_common.yaml.
    #
    # For each HTTP status, an intro block in `components/examples` (at the
    # end of this file) lists the referenceable response(s) and all example
    # ingredients available for local response definitions.
    #
    # APIs that return API-specific error codes, or a code combination not
    # covered by this catalogue, define the error response locally — combining
    # the ErrorInfo schema with a local restriction of `status` and `code` to
    # exactly the codes the API can return — and reference the shared examples:
    #   $ref: "../common/CAMARA_common.yaml#/components/examples/<EXAMPLE_NAME>"
    # A complete, copy-ready locally defined response is demonstrated in the
    # API templates (artifacts/api-templates/sample-service.yaml) — use it as
    # the skeleton for codes or combinations this catalogue does not cover.
    #
    # Statuses that are not documented by default (405, 406, 412, 415, 5xx —
    # see the CAMARA API Design Guide) have no referenceable response; their
    # canonical examples remain available for APIs with a justified use case.
    # ─────────────────────────────────────────────────────────────────────────

    BadRequest400:
      description: Bad Request
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum:
                      - 400
                  code:
                    enum:
                      - INVALID_ARGUMENT
          examples:
            GENERIC_400_INVALID_ARGUMENT:
              $ref: "#/components/examples/GENERIC_400_INVALID_ARGUMENT"

    # 400 variant for APIs with range-restricted fields or filter criteria
    BadRequestWithRange400:
      description: Bad Request
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum:
                      - 400
                  code:
                    enum:
                      - INVALID_ARGUMENT
                      - OUT_OF_RANGE
          examples:
            GENERIC_400_INVALID_ARGUMENT:
              $ref: "#/components/examples/GENERIC_400_INVALID_ARGUMENT"
            GENERIC_400_OUT_OF_RANGE:
              $ref: "#/components/examples/GENERIC_400_OUT_OF_RANGE"

    Unauthenticated401:
      description: Unauthorized
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum:
                      - 401
                  code:
                    enum:
                      - UNAUTHENTICATED
          examples:
            GENERIC_401_UNAUTHENTICATED:
              $ref: "#/components/examples/GENERIC_401_UNAUTHENTICATED"

    PermissionDenied403:
      description: Forbidden
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum:
                      - 403
                  code:
                    enum:
                      - PERMISSION_DENIED
          examples:
            GENERIC_403_PERMISSION_DENIED:
              $ref: "#/components/examples/GENERIC_403_PERMISSION_DENIED"

    # 404 for resource-oriented operations (resource addressed by path or query)
    NotFound404:
      description: Not found
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum:
                      - 404
                  code:
                    enum:
                      - NOT_FOUND
          examples:
            GENERIC_404_NOT_FOUND:
              $ref: "#/components/examples/GENERIC_404_NOT_FOUND"

    # 404 for APIs identifying their subject by device or phone number
    IdentifierNotFound404:
      description: Not found
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum:
                      - 404
                  code:
                    enum:
                      - IDENTIFIER_NOT_FOUND
          examples:
            GENERIC_404_IDENTIFIER_NOT_FOUND:
              $ref: "#/components/examples/GENERIC_404_IDENTIFIER_NOT_FOUND"

    # 409 for resource-creating operations; for subscription creation see
    # CreateSubscriptionConflict409 in CAMARA_event_common.yaml
    AlreadyExists409:
      description: Conflict
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum:
                      - 409
                  code:
                    enum:
                      - ALREADY_EXISTS
          examples:
            GENERIC_409_ALREADY_EXISTS:
              $ref: "#/components/examples/GENERIC_409_ALREADY_EXISTS"

    # 422 for APIs identifying their subject with the Device object
    DeviceIdentifier422:
      description: Unprocessable Content
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum:
                      - 422
                  code:
                    enum:
                      - SERVICE_NOT_APPLICABLE
                      - MISSING_IDENTIFIER
                      - UNSUPPORTED_IDENTIFIER
                      - UNNECESSARY_IDENTIFIER
          examples:
            GENERIC_422_SERVICE_NOT_APPLICABLE:
              $ref: "#/components/examples/GENERIC_422_SERVICE_NOT_APPLICABLE"
            GENERIC_422_MISSING_IDENTIFIER_DEVICE:
              $ref: "#/components/examples/GENERIC_422_MISSING_IDENTIFIER_DEVICE"
            GENERIC_422_UNSUPPORTED_IDENTIFIER_DEVICE:
              $ref: "#/components/examples/GENERIC_422_UNSUPPORTED_IDENTIFIER_DEVICE"
            GENERIC_422_UNNECESSARY_IDENTIFIER_DEVICE:
              $ref: "#/components/examples/GENERIC_422_UNNECESSARY_IDENTIFIER_DEVICE"

    # 422 for APIs identifying their subject with a phoneNumber field
    PhoneNumberIdentifier422:
      description: Unprocessable Content
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum:
                      - 422
                  code:
                    enum:
                      - SERVICE_NOT_APPLICABLE
                      - MISSING_IDENTIFIER
                      - UNNECESSARY_IDENTIFIER
          examples:
            GENERIC_422_SERVICE_NOT_APPLICABLE:
              $ref: "#/components/examples/GENERIC_422_SERVICE_NOT_APPLICABLE"
            GENERIC_422_MISSING_IDENTIFIER_PHONE_NUMBER:
              $ref: "#/components/examples/GENERIC_422_MISSING_IDENTIFIER_PHONE_NUMBER"
            GENERIC_422_UNNECESSARY_IDENTIFIER_PHONE_NUMBER:
              $ref: "#/components/examples/GENERIC_422_UNNECESSARY_IDENTIFIER_PHONE_NUMBER"

    TooManyRequests429:
      description: Too Many Requests
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum:
                      - 429
                  code:
                    enum:
                      - TOO_MANY_REQUESTS
          examples:
            GENERIC_429_TOO_MANY_REQUESTS:
              $ref: "#/components/examples/GENERIC_429_TOO_MANY_REQUESTS"

    # ─────────────────────────────────────────────────────────────────────────
    # DEPRECATED error responses
    #
    # The Generic* responses below are DEPRECATED as of Commonalities 0.9.0
    # and are planned for removal — or downgrade to a commented-out reference —
    # in the next meta-release cycle. They bundle error codes that do not apply
    # to every referencing API; new and realigning API versions use the
    # catalogue responses above, or define error responses locally from the
    # shared examples.
    #
    # Replacements:
    #   Generic400 → BadRequestWithRange400 (or BadRequest400)
    #   Generic401 → Unauthenticated401
    #   Generic403 → PermissionDenied403
    #   Generic404 → NotFound404 and/or IdentifierNotFound404
    #   Generic409 → AlreadyExists409; CreateSubscriptionConflict409
    #                (CAMARA_event_common.yaml) for subscription creation;
    #                local definition from the ABORTED / INCOMPATIBLE_STATE
    #                examples otherwise
    #   Generic410 → SinkGone410 (CAMARA_event_common.yaml) in notification
    #                callbacks; local definition from GENERIC_410_GONE otherwise
    #   Generic422 → DeviceIdentifier422 or PhoneNumberIdentifier422
    #   Generic429 → TooManyRequests429
    #   Generic405, Generic406, Generic412, Generic415, Generic5xx →
    #                local definition from the corresponding examples
    #                (statuses not documented by default)
    #
    # Content below is frozen apart from two bug fixes:
    #   - INVALID_TOKEN_CONTEXT removed from Generic403
    #     (https://github.com/camaraproject/Commonalities/issues/662)
    #   - deprecated code CONFLICT removed from Generic409
    # ─────────────────────────────────────────────────────────────────────────

    # DEPRECATED — use BadRequestWithRange400 (or BadRequest400) instead
    Generic400:
      description: Bad Request
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum:
                      - 400
                  code:
                    enum:
                      - INVALID_ARGUMENT
                      - OUT_OF_RANGE
                      # - "{{SPECIFIC_CODE}}" - API-specific codes added if needed
          examples:
            GENERIC_400_INVALID_ARGUMENT:
              description: Invalid Argument. Generic Syntax Exception
              value:
                status: 400
                code: INVALID_ARGUMENT
                message: Client specified an invalid argument, request body or query param.
            GENERIC_400_OUT_OF_RANGE:
              description: Out of Range. Specific Syntax Exception used when a given field has a pre-defined range or a invalid filter criteria combination is requested
              value:
                status: 400
                code: OUT_OF_RANGE
                message: Client specified an invalid range.
                # GENERIC_400_{{SPECIFIC_CODE}}:
                #   description: Specific Syntax Exception regarding a field that is relevant in the context of the API
                #   value:
                #     status: 400
                #     code: "{{SPECIFIC_CODE}}"
                #     message: Message for specific code
    # DEPRECATED — use Unauthenticated401 instead
    Generic401:
      description: Unauthorized
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum:
                      - 401
                  code:
                    enum:
                      - UNAUTHENTICATED
          examples:
            GENERIC_401_UNAUTHENTICATED:
              description: Request cannot be authenticated and a new authentication is required
              value:
                status: 401
                code: UNAUTHENTICATED
                message: Request not authenticated due to missing, invalid, or expired credentials. A new authentication is required.
    # DEPRECATED — use PermissionDenied403 instead
    Generic403:
      description: Forbidden
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum:
                      - 403
                  code:
                    enum:
                      - PERMISSION_DENIED
                      # INVALID_TOKEN_CONTEXT removed: it applies only to the few
                      # APIs whose scope allows confirming the match between a
                      # supplied identity and the access token; those APIs define
                      # the code and its example locally.
                      # - INVALID_TOKEN_CONTEXT
                      # - "{{SPECIFIC_CODE}}" - API-specific codes added if needed
          examples:
            GENERIC_403_PERMISSION_DENIED:
              description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security
              value:
                status: 403
                code: PERMISSION_DENIED
                message: Client does not have sufficient permissions to perform this action.
                # GENERIC_403_INVALID_TOKEN_CONTEXT removed together with the
                # INVALID_TOKEN_CONTEXT code
                # GENERIC_403_{{SPECIFIC_CODE}}:
                #   description: Indicate a Business Logic condition that forbids a process not attached to a specific field in the context of the API
                #   value:
                #     status: 403
                #     code: "{{SPECIFIC_CODE}}"
                #     message: Message for specific code
    # DEPRECATED — use NotFound404 and/or IdentifierNotFound404 instead
    Generic404:
      description: Not found
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum:
                      - 404
                  code:
                    enum:
                      - NOT_FOUND
                      - IDENTIFIER_NOT_FOUND
                      # - "{{SPECIFIC_CODE}}" - API-specific codes added if needed
          examples:
            GENERIC_404_NOT_FOUND:
              description: Resource is not found
              value:
                status: 404
                code: NOT_FOUND
                message: The specified resource is not found.
            GENERIC_404_IDENTIFIER_NOT_FOUND:
              description: Some identifier cannot be matched to a device
              value:
                status: 404
                code: IDENTIFIER_NOT_FOUND
                message: Device identifier not found.
                # GENERIC_404_{{SPECIFIC_CODE}}:
                #   description: Specific situation to highlight the resource/concept not found
                #   value:
                #     status: 404
                #     code: "{{SPECIFIC_CODE}}"
                #     message: Message for specific code
    # DEPRECATED — define locally from GENERIC_405_METHOD_NOT_ALLOWED if needed
    Generic405:
      description: Method Not Allowed
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum:
                      - 405
                  code:
                    enum:
                      - METHOD_NOT_ALLOWED
          examples:
            GENERIC_405_METHOD_NOT_ALLOWED:
              description: Invalid HTTP verb used with a given endpoint
              value:
                status: 405
                code: METHOD_NOT_ALLOWED
                message: The requested method is not allowed/supported on the target resource.
    # DEPRECATED — define locally from GENERIC_406_NOT_ACCEPTABLE if needed
    Generic406:
      description: Not Acceptable
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum:
                      - 406
                  code:
                    enum:
                      - NOT_ACCEPTABLE
          examples:
            GENERIC_406_NOT_ACCEPTABLE:
              description: API Server does not accept the media type (`Accept-*` header) indicated by API client
              value:
                status: 406
                code: NOT_ACCEPTABLE
                message: The server cannot produce a response matching the content requested by the client through `Accept-*` headers.
    # DEPRECATED — use AlreadyExists409 or a local definition; for subscription
    # creation see CreateSubscriptionConflict409 in CAMARA_event_common.yaml
    Generic409:
      description: Conflict
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum:
                      - 409
                  code:
                    enum:
                      - ABORTED
                      - ALREADY_EXISTS
                      # deprecated code CONFLICT removed
                      - INCOMPATIBLE_STATE
                      # - "{{SPECIFIC_CODE}}" - API-specific codes added if needed
          examples:
            GENERIC_409_ABORTED:
              description: The resource is undergoing modification by another process
              value:
                status: 409
                code: ABORTED
                message: Resource is being modified by another operation. Please wait, and retry if appropriate.
            GENERIC_409_ALREADY_EXISTS:
              description: Trying to create an existing resource
              value:
                status: 409
                code: ALREADY_EXISTS
                message: The resource that a client tried to create already exists.
            GENERIC_409_INCOMPATIBLE_STATE:
              description: |
                The status of the referenced resource is not compatible.
              value:
                status: 409
                code: INCOMPATIBLE_STATE
                message: Resource must be in AVAILABLE state to extend. Current state is UNAVAILABLE.
                # GENERIC_409_{{SPECIFIC_CODE}}:
                #   description: Specific conflict situation that is relevant in the context of the API
                #   value:
                #     status: 409
                #     code: "{{SPECIFIC_CODE}}"
                #     message: Message for specific code
    # DEPRECATED — use SinkGone410 (CAMARA_event_common.yaml) or a local
    # definition instead
    Generic410:
      description: Gone
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum:
                      - 410
                  code:
                    enum:
                      - GONE
          examples:
            GENERIC_410_GONE:
              description: Use in notifications flow to allow API Consumer to indicate that its callback is no longer available
              value:
                status: 410
                code: GONE
                message: Access to the target resource is no longer available.
    # DEPRECATED — define locally from GENERIC_412_FAILED_PRECONDITION if needed
    Generic412:
      description: Failed precondition
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum:
                      - 412
                  code:
                    enum:
                      - FAILED_PRECONDITION
          examples:
            GENERIC_412_FAILED_PRECONDITION:
              description: Indication by the API Server that the request cannot be processed in current system state
              value:
                status: 412
                code: FAILED_PRECONDITION
                message: Request cannot be executed in the current system state.
    # DEPRECATED — define locally from GENERIC_415_UNSUPPORTED_MEDIA_TYPE if needed
    Generic415:
      description: Unsupported Media Type
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum:
                      - 415
                  code:
                    enum:
                      - UNSUPPORTED_MEDIA_TYPE
          examples:
            GENERIC_415_UNSUPPORTED_MEDIA_TYPE:
              description: Payload format of the request is in an unsupported format by the Server. Should not happen
              value:
                status: 415
                code: UNSUPPORTED_MEDIA_TYPE
                message: The server refuses to accept the request because the payload format is in an unsupported format.
    # DEPRECATED — use DeviceIdentifier422 or PhoneNumberIdentifier422 instead
    Generic422:
      description: Unprocessable Content
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum:
                      - 422
                  code:
                    enum:
                      - SERVICE_NOT_APPLICABLE
                      - MISSING_IDENTIFIER
                      - UNSUPPORTED_IDENTIFIER
                      - UNNECESSARY_IDENTIFIER
                      # - "{{SPECIFIC_CODE}}" - API-specific codes added if needed
          examples:
            GENERIC_422_SERVICE_NOT_APPLICABLE:
              description: Service not applicable for the provided identifier
              value:
                status: 422
                code: SERVICE_NOT_APPLICABLE
                message: The service is not available for the provided identifier.
            GENERIC_422_MISSING_IDENTIFIER:
              description: An identifier is not included in the request and the device or phone number identification cannot be derived from the access token
              value:
                status: 422
                code: MISSING_IDENTIFIER
                message: The device cannot be identified.
            GENERIC_422_UNSUPPORTED_IDENTIFIER:
              description: None of the provided identifiers is supported by the implementation
              value:
                status: 422
                code: UNSUPPORTED_IDENTIFIER
                message: The identifier provided is not supported.
            GENERIC_422_UNNECESSARY_IDENTIFIER:
              description: An explicit identifier is provided when a device or phone number has already been identified from the access token
              value:
                status: 422
                code: UNNECESSARY_IDENTIFIER
                message: The device is already identified by the access token.
                # GENERIC_422_{{SPECIFIC_CODE}}:
                #   description: Any semantic condition associated to business logic, specifically related to a field or data structure
                #   value:
                #     status: 422
                #     code: "{{SPECIFIC_CODE}}"
                #     message: Message for specific code
    # DEPRECATED — use TooManyRequests429 instead
    Generic429:
      description: Too Many Requests
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum:
                      - 429
                  code:
                    enum:
                      - QUOTA_EXCEEDED
                      - TOO_MANY_REQUESTS
          examples:
            GENERIC_429_QUOTA_EXCEEDED:
              description: Request is rejected due to exceeding a business quota limit
              value:
                status: 429
                code: QUOTA_EXCEEDED
                message: Out of resource quota.
            GENERIC_429_TOO_MANY_REQUESTS:
              description: Access to the API has been temporarily blocked due to rate or spike arrest limits being reached
              value:
                status: 429
                code: TOO_MANY_REQUESTS
                message: Rate limit reached.
    # DEPRECATED — define locally from GENERIC_500_INTERNAL if needed
    Generic500:
      description: Internal Server Error
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum:
                      - 500
                  code:
                    enum:
                      - INTERNAL
          examples:
            GENERIC_500_INTERNAL:
              description: Problem in Server side. Regular Server Exception
              value:
                status: 500
                code: INTERNAL
                message: Unknown server error. Typically a server bug.
    # DEPRECATED — define locally from GENERIC_501_NOT_IMPLEMENTED if needed
    Generic501:
      description: Not Implemented
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum:
                      - 501
                  code:
                    enum:
                      - NOT_IMPLEMENTED
          examples:
            GENERIC_501_NOT_IMPLEMENTED:
              description: Service not implemented. The use of this code should be avoided as far as possible to get the objective to reach aligned implementations
              value:
                status: 501
                code: NOT_IMPLEMENTED
                message: This functionality is not implemented yet.
    # DEPRECATED — define locally from GENERIC_502_BAD_GATEWAY if needed
    Generic502:
      description: Bad Gateway
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum:
                      - 502
                  code:
                    enum:
                      - BAD_GATEWAY
          examples:
            GENERIC_502_BAD_GATEWAY:
              description: Internal routing problem in the Server side that blocks to manage the service properly
              value:
                status: 502
                code: BAD_GATEWAY
                message: An upstream internal service cannot be reached.
    # DEPRECATED — define locally from GENERIC_503_UNAVAILABLE if needed
    Generic503:
      description: Service Unavailable
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum:
                      - 503
                  code:
                    enum:
                      - UNAVAILABLE
          examples:
            GENERIC_503_UNAVAILABLE:
              description: Service is not available. Temporary situation usually related to maintenance process in the server side
              value:
                status: 503
                code: UNAVAILABLE
                message: Service Unavailable.
    # DEPRECATED — define locally from GENERIC_504_TIMEOUT if needed
    Generic504:
      description: Gateway Timeout
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum:
                      - 504
                  code:
                    enum:
                      - TIMEOUT
          examples:
            GENERIC_504_TIMEOUT:
              description: API Server Timeout
              value:
                status: 504
                code: TIMEOUT
                message: Request timeout exceeded.

  examples:
    # ─────────────────────────────────────────────────────────────────────────
    # Error examples — reusable ingredients
    #
    # Canonical examples for the CAMARA error codes. The catalogue responses
    # above reference them, and locally defined error responses in APIs
    # reference them the same way (see the intro of `responses`), keeping the
    # error wording consistent across CAMARA APIs.
    #
    # Each status intro below lists the referenceable generic response(s) —
    # in this file or in CAMARA_event_common.yaml — and the example
    # ingredients available for local response definitions.
    # ─────────────────────────────────────────────────────────────────────────

    # ── 400 Bad Request ──────────────────────────────────────────────────────
    # Responses: BadRequest400, BadRequestWithRange400; for subscription
    #   creation: CreateSubscriptionBadRequest400 and SubscriptionIdRequired400
    #   (CAMARA_event_common.yaml)
    # Examples: GENERIC_400_INVALID_ARGUMENT, GENERIC_400_OUT_OF_RANGE
    GENERIC_400_INVALID_ARGUMENT:
      description: Invalid Argument. Generic Syntax Exception
      value:
        status: 400
        code: INVALID_ARGUMENT
        message: Client specified an invalid argument, request body or query param.
    GENERIC_400_OUT_OF_RANGE:
      description: Out of Range. Specific Syntax Exception used when a given field has a pre-defined range or a invalid filter criteria combination is requested
      value:
        status: 400
        code: OUT_OF_RANGE
        message: Client specified an invalid range.

    # ── 401 Unauthorized ─────────────────────────────────────────────────────
    # Responses: Unauthenticated401
    # Examples: GENERIC_401_UNAUTHENTICATED
    GENERIC_401_UNAUTHENTICATED:
      description: Request cannot be authenticated and a new authentication is required
      value:
        status: 401
        code: UNAUTHENTICATED
        message: Request not authenticated due to missing, invalid, or expired credentials. A new authentication is required.

    # ── 403 Forbidden ────────────────────────────────────────────────────────
    # Responses: PermissionDenied403; for subscriptions:
    #   SubscriptionPermissionDenied403 (CAMARA_event_common.yaml)
    # Examples: GENERIC_403_PERMISSION_DENIED
    # Note: INVALID_TOKEN_CONTEXT deliberately has no shared example — the few
    #   APIs whose scope allows confirming an identity match define the code
    #   and its example locally.
    GENERIC_403_PERMISSION_DENIED:
      description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security
      value:
        status: 403
        code: PERMISSION_DENIED
        message: Client does not have sufficient permissions to perform this action.

    # ── 404 Not Found ────────────────────────────────────────────────────────
    # Responses: NotFound404, IdentifierNotFound404
    # Examples: GENERIC_404_NOT_FOUND, GENERIC_404_IDENTIFIER_NOT_FOUND
    GENERIC_404_NOT_FOUND:
      description: Resource is not found
      value:
        status: 404
        code: NOT_FOUND
        message: The specified resource is not found.
    GENERIC_404_IDENTIFIER_NOT_FOUND:
      description: The identifier cannot be matched to a device or phone number
      value:
        status: 404
        code: IDENTIFIER_NOT_FOUND
        message: The identifier is not found.

    # ── 405 Method Not Allowed (not documented by default) ───────────────────
    # Responses: none — define locally if a use case justifies documenting it
    # Examples: GENERIC_405_METHOD_NOT_ALLOWED
    GENERIC_405_METHOD_NOT_ALLOWED:
      description: Invalid HTTP verb used with a given endpoint
      value:
        status: 405
        code: METHOD_NOT_ALLOWED
        message: The requested method is not allowed/supported on the target resource.

    # ── 406 Not Acceptable (not documented by default) ───────────────────────
    # Responses: none — define locally if a use case justifies documenting it
    # Examples: GENERIC_406_NOT_ACCEPTABLE
    GENERIC_406_NOT_ACCEPTABLE:
      description: API Server does not accept the media type (`Accept-*` header) indicated by API client
      value:
        status: 406
        code: NOT_ACCEPTABLE
        message: The server cannot produce a response matching the content requested by the client through `Accept-*` headers.

    # ── 409 Conflict ─────────────────────────────────────────────────────────
    # Responses: AlreadyExists409; for subscription creation:
    #   CreateSubscriptionConflict409 (CAMARA_event_common.yaml)
    # Examples: GENERIC_409_ALREADY_EXISTS, GENERIC_409_ABORTED,
    #   GENERIC_409_INCOMPATIBLE_STATE (the deprecated code CONFLICT is removed)
    GENERIC_409_ALREADY_EXISTS:
      description: Trying to create an existing resource
      value:
        status: 409
        code: ALREADY_EXISTS
        message: The resource that a client tried to create already exists.
    GENERIC_409_ABORTED:
      description: The resource is undergoing modification by another process
      value:
        status: 409
        code: ABORTED
        message: Resource is being modified by another operation. Please wait, and retry if appropriate.
    GENERIC_409_INCOMPATIBLE_STATE:
      description: The status of the referenced resource is not compatible
      value:
        status: 409
        code: INCOMPATIBLE_STATE
        message: Resource must be in AVAILABLE state to extend. Current state is UNAVAILABLE.

    # ── 410 Gone ─────────────────────────────────────────────────────────────
    # Responses: SinkGone410 (CAMARA_event_common.yaml) for notification
    #   callbacks; define locally for a direct resource-gone use case
    # Examples: GENERIC_410_GONE
    GENERIC_410_GONE:
      description: Use in notifications flow to allow API Consumer to indicate that its callback is no longer available
      value:
        status: 410
        code: GONE
        message: Access to the target resource is no longer available.

    # ── 412 Precondition Failed (not documented by default) ──────────────────
    # Responses: none — define locally if a use case justifies documenting it
    # Examples: GENERIC_412_FAILED_PRECONDITION
    GENERIC_412_FAILED_PRECONDITION:
      description: Indication by the API Server that the request cannot be processed in current system state
      value:
        status: 412
        code: FAILED_PRECONDITION
        message: Request cannot be executed in the current system state.

    # ── 415 Unsupported Media Type (not documented by default) ───────────────
    # Responses: none — define locally if a use case justifies documenting it
    # Examples: GENERIC_415_UNSUPPORTED_MEDIA_TYPE
    GENERIC_415_UNSUPPORTED_MEDIA_TYPE:
      description: Payload format of the request is in an unsupported format by the Server. Should not happen
      value:
        status: 415
        code: UNSUPPORTED_MEDIA_TYPE
        message: The server refuses to accept the request because the payload format is in an unsupported format.

    # ── 422 Unprocessable Content ────────────────────────────────────────────
    # Responses: DeviceIdentifier422, PhoneNumberIdentifier422; for
    #   subscription creation: CreateSubscriptionDevice422 and
    #   CreateSubscriptionPhoneNumber422 (CAMARA_event_common.yaml)
    # Examples: GENERIC_422_SERVICE_NOT_APPLICABLE (subject-neutral) and the
    #   identifier examples in device / phone number wording variants
    GENERIC_422_SERVICE_NOT_APPLICABLE:
      description: Service not applicable for the provided identifier
      value:
        status: 422
        code: SERVICE_NOT_APPLICABLE
        message: The service is not available for the provided identifier.
    GENERIC_422_MISSING_IDENTIFIER_DEVICE:
      description: The device identifier is not included in the request and the device cannot be derived from the access token
      value:
        status: 422
        code: MISSING_IDENTIFIER
        message: The device cannot be identified.
    GENERIC_422_UNSUPPORTED_IDENTIFIER_DEVICE:
      description: None of the provided device identifiers is supported by the implementation
      value:
        status: 422
        code: UNSUPPORTED_IDENTIFIER
        message: The identifier provided is not supported.
    GENERIC_422_UNNECESSARY_IDENTIFIER_DEVICE:
      description: An explicit device identifier is provided when the device has already been identified from the access token
      value:
        status: 422
        code: UNNECESSARY_IDENTIFIER
        message: The device is already identified by the access token.
    GENERIC_422_MISSING_IDENTIFIER_PHONE_NUMBER:
      description: The phone number is not included in the request and cannot be derived from the access token
      value:
        status: 422
        code: MISSING_IDENTIFIER
        message: The phone number cannot be identified.
    GENERIC_422_UNNECESSARY_IDENTIFIER_PHONE_NUMBER:
      description: An explicit phone number is provided when the phone number has already been identified from the access token
      value:
        status: 422
        code: UNNECESSARY_IDENTIFIER
        message: The phone number is already identified by the access token.

    # ── 429 Too Many Requests ────────────────────────────────────────────────
    # Responses: TooManyRequests429
    # Examples: GENERIC_429_TOO_MANY_REQUESTS, GENERIC_429_QUOTA_EXCEEDED
    GENERIC_429_TOO_MANY_REQUESTS:
      description: Access to the API has been temporarily blocked due to rate or spike arrest limits being reached
      value:
        status: 429
        code: TOO_MANY_REQUESTS
        message: Rate limit reached.
    GENERIC_429_QUOTA_EXCEEDED:
      description: Request is rejected due to exceeding a business quota limit
      value:
        status: 429
        code: QUOTA_EXCEEDED
        message: Out of resource quota.

    # ── 5xx Server errors (not documented by default) ────────────────────────
    # Responses: none — define locally if a use case justifies documenting it
    # Examples: GENERIC_500_INTERNAL, GENERIC_501_NOT_IMPLEMENTED,
    #   GENERIC_502_BAD_GATEWAY, GENERIC_503_UNAVAILABLE, GENERIC_504_TIMEOUT
    GENERIC_500_INTERNAL:
      description: Problem in Server side. Regular Server Exception
      value:
        status: 500
        code: INTERNAL
        message: Unknown server error. Typically a server bug.
    GENERIC_501_NOT_IMPLEMENTED:
      description: Service not implemented. The use of this code should be avoided as far as possible to get the objective to reach aligned implementations
      value:
        status: 501
        code: NOT_IMPLEMENTED
        message: This functionality is not implemented yet.
    GENERIC_502_BAD_GATEWAY:
      description: Internal routing problem in the Server side that blocks to manage the service properly
      value:
        status: 502
        code: BAD_GATEWAY
        message: An upstream internal service cannot be reached.
    GENERIC_503_UNAVAILABLE:
      description: Service is not available. Temporary situation usually related to maintenance process in the server side
      value:
        status: 503
        code: UNAVAILABLE
        message: Service Unavailable.
    GENERIC_504_TIMEOUT:
      description: API Server Timeout
      value:
        status: 504
        code: TIMEOUT
        message: Request timeout exceeded.