openapi.yaml

openapi: 3.1.0
info:
  title: Status List Server
  version: 0.1.0
  description: |
    REST API for the Status List Server.

    This service implements the
    [Token Status List specification](https://datatracker.ietf.org/doc/draft-ietf-oauth-status-list/)
    and allows credential issuers to register, publish, and update status lists.
    Relying parties can retrieve status list tokens in JWT or CWT format.

    Error responses are JSON objects of the form
    `{"error": "<code>", "error_description": "<human-readable text>"}`, served
    as `application/json` with `Cache-Control: no-store, max-age=0`. The
    `error` field is a stable machine-readable identifier and is the field
    clients should branch on — the HTTP status alone is not sufficient, since
    (for example) `409` covers both `status_list_already_exists` and
    `update_conflict`. `error_description` is for humans and its wording is not
    part of the contract.

    Status list tokens are signed by the server and delivered as
    `application/statuslist+jwt` or `application/statuslist+cwt`. JWT-format
    tokens are gzip-compressed only when the client requests it via
    `Accept-Encoding: gzip`; CWT-format tokens are never compressed.

    ## Rate limiting

    The server applies three independent token-bucket governor tiers, each
    operator-configurable through the `APP_RATE_LIMIT__*` environment
    variables (see `RateLimitConfig`):

      * **strict** (per source IP) — `POST /api/v1/credentials`.
        Tunables: `strict_burst_size`, `strict_period_secs`
        (defaults: 10 / 60s).
      * **writes** (per smart IP via `SmartIpKeyExtractor`, reading
        `X-Forwarded-For`, `X-Real-Ip`, and `Forwarded` headers, falling back to
        the peer IP) — `PUT`/`PATCH`
        `/api/v1/status-lists/{list_id}/statuses`.
        Tunables: `strict_burst_size`, `strict_period_secs`.
      * **permissive** (per source IP) — public read routes
        (`GET /api/v1/aggregation`,
        `GET /api/v1/status-lists/{list_id}`).
        Tunables: `permissive_burst_size`, `permissive_period_secs`
        (defaults: 100 / 60s).

    When a quota is exhausted the server returns `429 Too Many Requests`.

    ## Request bounds

    In addition to the rate limiter, the server enforces hard bounds on
    incoming requests and persisted status lists through the `APP_LIMITS__*`
    environment variables (see `LimitsConfig`):

    | Bound | Default | Exceeded response |
    |---|---|---|
    | `max_body_size_bytes` | 2 MiB | `413 Payload Too Large` |
    | `max_status_index` | 100000 | `400 Bad Request` (`index` too large) |
    | `max_statuses_per_request` | 5000 | `400 Bad Request` (too many entries) |
    | `max_serialized_list_size` | 1 MiB | `422 Unprocessable Entity` |

    These bounds are reflected on the request schemas (`StatusEntry.index`
    `maximum`, `StatusUpdateRequest.statuses` `maxItems`) for the default
    configuration; operators who lower a bound via configuration should treat
    the documented schema maximums as defaults, not guarantees.
  contact:
    name: adorsys Status List Server
    url: https://github.com/adorsys/status-list-server
  license:
    name: MIT OR Apache-2.0
    identifier: MIT OR Apache-2.0

servers:
  - url: https://{host}
    description: Status List Server
    variables:
      host:
        default: localhost:8000
        description: Host name and port of the server.

security:
  - BearerAuth: []

paths:
  /:
    get:
      operationId: welcome
      summary: Welcome page
      description: Returns a simple welcome message for the Status List Server.
      security: []
      responses:
        "200":
          description: Welcome message
          content:
            text/plain:
              schema:
                type: string
              example: "Status list Server"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /health/live:
    get:
      operationId: livenessCheck
      summary: Liveness check
      description: Returns a lightweight indicator that the HTTP server process is up.
      security: []
      responses:
        "200":
          description: Server process is up
          content:
            text/plain:
              schema:
                type: string
              example: "OK"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /health:
    get:
      operationId: legacyLivenessCheck
      summary: Liveness check alias
      description: Backward-compatible alias for `/health/live`.
      security: []
      responses:
        "200":
          description: Server process is up
          content:
            text/plain:
              schema:
                type: string
              example: "OK"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /health/ready:
    get:
      operationId: readinessCheck
      summary: Readiness check
      description: |
        Returns 200 only when all critical dependencies are reachable;
        otherwise 503. The public response is intentionally generic; detailed
        dependency failures are logged internally.
      security: []
      responses:
        "200":
          description: All critical dependencies are reachable
          content:
            text/plain:
              schema:
                type: string
              example: "READY"
        "503":
          description: One or more critical dependencies are unavailable
          content:
            text/plain:
              schema:
                type: string
              example: "NOT_READY"

  /metrics:
    get:
      operationId: getMetrics
      summary: Prometheus metrics
      description: |
        Returns Prometheus exposition format metrics when the server is started
        with `APP_SERVER__ENABLE_METRICS=true`. Returns a 404 response when
        metrics are disabled.
      security: []
      responses:
        "200":
          description: Prometheus metrics
          content:
            text/plain:
              schema:
                type: string
          headers:
            Content-Type:
              schema:
                type: string
              description: text/plain; version=0.0.4
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/credentials:
    post:
      operationId: registerIssuer
      summary: Register issuer credentials
      description: |
        Registers an issuer by storing its unique identifier and public key
        (JWK). The registered public key is used later to validate signed JWT
        Bearer tokens for the protected management endpoints.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CredentialsRequest"
      responses:
        "202":
          description: Credentials accepted and stored successfully
          content:
            text/plain:
              schema:
                type: string
              example: "Credentials stored successfully"
        "400":
          $ref: "#/components/responses/BadRequest"
        "409":
          $ref: "#/components/responses/CredentialConflict"
        "413":
          $ref: "#/components/responses/PayloadTooLarge"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/aggregation:
    get:
      operationId: getAggregation
      summary: Aggregate all status list URIs
      description: |
        Returns the `sub` URIs of every status list hosted by this server,
        issuer-agnostic. Intended for relying parties that need to enumerate
        the set of status lists to poll. The response is a JSON object with a
        single `status_lists` array of URI strings.

        When `server.aggregation_uri` is configured, that URI is advertised
        inside issued status list tokens (draft-21 §4.2/§4.3).
      security: []
      responses:
        "200":
          description: Aggregation of all hosted status list URIs.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AggregationResponse"
              example:
                status_lists:
                  - "https://statuslist.example.com/api/v1/status-lists/477121aa-b598-419e-916f-1e74654ff38b"
                  - "https://statuslist.example.com/api/v1/status-lists/8e4ebb4a-dd79-498f-ac97-966f22884037"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "503":
          $ref: "#/components/responses/ServiceUnavailable"

  /api/v1/status-lists/{list_id}/statuses:
    parameters:
      - name: list_id
        in: path
        required: true
        description: UUID of the status list.
        schema:
          type: string
          format: uuid
          example: "477121aa-b598-419e-916f-1e74654ff38b"

    put:
      operationId: publishStatusList
      summary: Publish a new status list
      description: |
        Creates a new status list for the given `list_id`. The issuer is
        derived from the validated JWT Bearer token. The request body defines
        the initial status entries for the list.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/StatusUpdateRequest"
      responses:
        "201":
          description: Status list created successfully
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "409":
          $ref: "#/components/responses/PublishConflict"
        "413":
          $ref: "#/components/responses/PayloadTooLarge"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"

    patch:
      operationId: updateStatusList
      summary: Update an existing status list
      description: |
        Updates the status entries of an existing status list. The JWT Bearer
        token must belong to the issuer that originally published the list.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/StatusUpdateRequest"
      responses:
        "200":
          description: Status list updated successfully
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/UpdateConflict"
        "413":
          $ref: "#/components/responses/PayloadTooLarge"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/UpdateInternalServerError"

  /api/v1/status-lists/{list_id}:
    get:
      operationId: getStatusList
      summary: Retrieve a status list token
      description: |
        Returns the status list token for the requested `list_id`, encoded as a
        JWT or CWT depending on the `Accept` header.

        JWT-format responses are gzip-compressed (`Content-Encoding: gzip`)
        only when the client has advertised support via `Accept-Encoding: gzip`
        (see draft-ietf-oauth-status-list-21 §8.2). CWT-format responses are
        never gzip-compressed. Because the representation varies by
        `Accept-Encoding`, every response carries `Vary: Accept-Encoding`.

        The decoded token conforms to the
        [OAuth Status List](https://datatracker.ietf.org/doc/draft-ietf-oauth-status-list/)
        specification. The token is signed by the server and contains an `x5c`
        certificate chain in the protected header (JWT) or protected header map
        (CWT) for verification.

        Supplying `?time=<unix-timestamp>` performs draft-21 §8.4 historical
        resolution. Historical snapshots are privacy-sensitive because they
        disclose timing information; deploy this capability only after
        considering the privacy implications in §12.7.
      security: []
      parameters:
        - name: list_id
          in: path
          required: true
          description: Identifier of the status list.
          schema:
            type: string
            example: "477121aa-b598-419e-916f-1e74654ff38b"
        - name: Accept
          in: header
          required: false
          description: |
            Desired token format. Defaults to `application/statuslist+jwt` if
            omitted.
          schema:
            type: string
            enum:
              - application/statuslist+jwt
              - application/statuslist+cwt
            default: application/statuslist+jwt
        - name: time
          in: query
          required: false
          description: |
            Unix timestamp for a historical Status List Token. A response is
            returned only when a retained token validity window covers this
            instant (`iat <= time < exp`).
          schema:
            type: integer
            format: int64
            example: 1686925000
        - name: Accept-Encoding
          in: header
          required: false
          description: |
            Content codings the client is willing to accept. When `gzip` is
            advertised (default q-value), JWT-format responses are
            gzip-compressed and carry `Content-Encoding: gzip`. CWT-format
            responses are never compressed regardless of this header.
          schema:
            type: string
            example: gzip
      responses:
        "200":
          description: |
            Status list token returned successfully. The decoded token payload
            conforms to `StatusListToken`.
          content:
            application/statuslist+jwt:
              schema:
                type: string
                format: binary
              example: "H4sIAAAAAAAAE6tW..."
            application/statuslist+cwt:
              schema:
                type: string
                format: binary
                description: |
                  Raw COSE_Sign1_Tagged CBOR bytes (CBOR tag 18). Never
                  gzip-compressed regardless of the request's `Accept-Encoding`.
              example: "0gEAAQ..."
          headers:
            Content-Encoding:
              schema:
                type: string
              description: |
                Present with value `gzip` only when the response body has been
                gzip-compressed. Compression is applied to JWT-format tokens
                (`application/statuslist+jwt`) exclusively, and only when the
                client has advertised support for it via an
                `Accept-Encoding: gzip` request header. CWT-format tokens are
                never compressed. Absent otherwise.
              example: gzip
            Vary:
              schema:
                type: string
              description: |
                Always `Accept-Encoding`. Because the response body varies by
                the request's `Accept-Encoding` header, this is required so
                that shared caches/CDNs do not serve a gzipped variant to a
                client that did not request one (RFC 9111 §4.2).
              example: Accept-Encoding
        "404":
          $ref: "#/components/responses/NotFound"
        "406":
          $ref: "#/components/responses/NotAcceptable"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "503":
          $ref: "#/components/responses/ServiceUnavailable"

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        Signed JWT Bearer token. The token must be signed with the private key
        corresponding to the public key registered for the issuer. The payload
        must contain:

        - `iss`: the registered issuer identifier
        - `iat`: issued-at timestamp
        - `exp`: expiration timestamp

        The server validates the signature using the registered JWK and verifies
        that the `iss` claim matches the registered issuer.

        Mutual TLS (mTLS) for issuer authentication is not implemented in the
        current release; this security scheme may be added in a future version.

  schemas:
    CredentialsRequest:
      type: object
      required:
        - issuer
        - public_key
      properties:
        issuer:
          type: string
          description: Unique identifier of the issuer.
          example: "my-issuer"
        public_key:
          $ref: "#/components/schemas/JWK"

    JWK:
      type: object
      description: |
        JSON Web Key representing the issuer's public key. The exact fields
        depend on the key type (e.g., `kty`, `crv`, `x`, `y` for EC keys).
      required:
        - kty
      properties:
        kty:
          type: string
          description: Key type.
          example: "EC"
        crv:
          type: string
          description: Curve name for EC keys.
          example: "P-256"
        x:
          type: string
          description: X coordinate of the public key.
          example: "NeyFv_2L67OEplNbJpR02IFis4_lFW9HYmhfF5Or6m8"
        y:
          type: string
          description: Y coordinate of the public key.
          example: "eAH2qe8Pg3GQ28uxA8-qNAqdwQ_zfV2uKAvJ2sLpY9M"
      example:
        kty: "EC"
        crv: "P-256"
        x: "NeyFv_2L67OEplNbJpR02IFis4_lFW9HYmhfF5Or6m8"
        y: "eAH2qe8Pg3GQ28uxA8-qNAqdwQ_zfV2uKAvJ2sLpY9M"

    StatusUpdateRequest:
      type: object
      description: |
        Request payload for creating (`PUT`) or updating (`PATCH`) status
        entries in a status list. The number of entries is bounded by the
        operator-configurable `limits.max_statuses_per_request` (default 5000);
        a request exceeding that bound is rejected with `400 Bad Request`.
      required:
        - statuses
      properties:
        statuses:
          type: array
          description: Array of status entries to create or update.
          maxItems: 5000
          items:
            $ref: "#/components/schemas/StatusEntry"

    StatusEntry:
      type: object
      required:
        - index
        - status
      properties:
        index:
          type: integer
          format: int32
          minimum: 0
          maximum: 100000
          description: |
            Position of the referenced token in the status list. The maximum
            accepted value is bounded by the operator-configurable
            `limits.max_status_index` (default 100000); a request with an
            index above that bound is rejected with `400 Bad Request`.
          example: 42
        status:
          $ref: "#/components/schemas/StatusValue"

    StatusValue:
      type: string
      description: "Status value."
      enum:
        - VALID
        - INVALID
        - SUSPENDED
      example: "INVALID"

    StatusList:
      type: object
      description: |
        Bit-string representation of the status list. The `lst` field contains
        a zlib-compressed, base64url-encoded byte array where each referenced
        token occupies `bits` bits. The first bit of the byte array is the status
        for index 0.
      required:
        - bits
        - lst
      properties:
        bits:
          type: integer
          description: Number of bits used for each status entry.
          enum:
            - 1
            - 2
            - 4
            - 8
          example: 1
        lst:
          type: string
          description: |
            Base64url-encoded zlib-compressed status byte array.
          example: "eJxLTAQAASUAw3s"

    StatusListToken:
      type: object
      description: |
        Decoded payload of a JWT or CWT status list token. The actual response
        from `GET /statuslists/{list_id}` is the signed token — a JWT string
        (optionally gzip-compressed when the client requests it) or raw
        COSE_Sign1_Tagged CBOR bytes for CWT. The token is signed by the server
        using the configured signing key and contains the certificate chain in
        the `x5c` header (JWT) or protected header (CWT).
      required:
        - sub
        - iat
        - status_list
      properties:
        iss:
          type: string
          description: Issuer identifier of the status list server.
          example: "https://statuslist.example.com"
        sub:
          type: string
          description: URI of the status list.
          example: "https://statuslist.example.com/statuslists/477121aa-b598-419e-916f-1e74654ff38b"
        iat:
          type: integer
          description: Issued-at timestamp (seconds since Unix epoch).
          example: 1752515200
        exp:
          type: integer
          description: Expiration timestamp (seconds since Unix epoch).
          example: 1752516100
        ttl:
          type: integer
          description: Recommended time-to-live in seconds for caching the token.
          example: 300
        status_list:
          $ref: "#/components/schemas/StatusList"

    AggregationResponse:
      type: object
      description: |
        Response body of `GET /api/v1/aggregation`. Contains the `sub` URIs of
        every status list hosted by the server, issuer-agnostic.
      required:
        - status_lists
      properties:
        status_lists:
          type: array
          description: URIs of all hosted status lists.
          items:
            type: string
            format: uri
          example:
            - "https://statuslist.example.com/api/v1/status-lists/477121aa-b598-419e-916f-1e74654ff38b"
            - "https://statuslist.example.com/api/v1/status-lists/8e4ebb4a-dd79-498f-ac97-966f22884037"

    ErrorResponse:
      type: object
      description: |
        The error body returned by every JSON error response. Serialized from
        `server::error::ErrorResponse`.

        This shape follows the `cloud-identity-wallet` house pattern used for
        cross-project consistency across ADORSYS identity services.
      required:
        - error
      properties:
        error:
          type: string
          description: |
            Stable machine-readable error identifier. Branch on this rather
            than on the HTTP status, which is not unique across error kinds.
          enum:
            # 400
            - invalid_list_id
            - invalid_query
            - invalid_input
            - invalid_index
            - invalid_historical_time
            - invalid_public_jwk
            - too_many_statuses
            - index_too_large
            # 401 — emitted by the authentication middleware
            - invalid_auth_header
            - jwt_error
            - unsupported_algorithm
            - issuer_not_found
            # 403
            - issuer_mismatch
            # 404
            - status_list_not_found
            - historical_status_list_not_found
            # 406
            - invalid_accept_header
            # 409
            - status_list_already_exists
            - credentials_already_exist
            - update_conflict
            - write_contention
            # 413
            - payload_too_large
            # 422
            - status_too_large
            # 429
            - too_many_requests
            # 500 / 503
            - internal_error
            - service_unavailable
          example: "status_list_already_exists"
        error_description:
          type: string
          description: |
            Human-readable explanation. Omitted when absent; wording is not
            part of the contract and may change without notice.
          example: "Status list already exists"

  responses:
    BadRequest:
      description: |
        Invalid request data. In addition to schema/validation failures
        (e.g. a non-UUID `list_id`), this status is returned when an enforced
        request bound is exceeded:

          * number of status entries exceeds
            `limits.max_statuses_per_request` (default 5000) —
            `Too many statuses in request: <count> > <max>`; or
          * a status `index` exceeds `limits.max_status_index`
            (default 100000) — `Status index <n> exceeds the configured
            maximum`.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            error: "too_many_statuses"
            error_description: "too many statuses in request: 6000 > 5000"

    Unauthorized:
      description: Missing or invalid authentication token
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            error: "invalid_auth_header"
            error_description: "Missing or invalid Authorization header"

    Forbidden:
      description: Insufficient permissions to access the resource
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            error: "issuer_mismatch"
            error_description: "Issuer does not own the status list"

    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            error: "status_list_not_found"
            error_description: "Status list was not found"

    NotAcceptable:
      description: Requested response format not supported
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            error: "invalid_accept_header"
            error_description: "Invalid accept header"

    PublishConflict:
      description: |
        The publish was rejected. Read the `error` field: the two cases below
        require opposite client behaviour, and only one of them is retryable.

        `status_list_already_exists` — a list with this `list_id` is already
        published. **Retrying will never succeed**; choose a different `list_id`
        or update the existing list instead.

        `write_contention` — the write lost a lock race inside the database
        (deadlock or lock-wait timeout) and was rolled back. Nothing was created,
        so **retry the identical request**. A `Retry-After` header gives a floor;
        add jitter on top, since the writers that just collided would otherwise
        resynchronise.
      headers:
        Retry-After:
          description: |
            Present only for `write_contention`. Seconds to wait before
            retrying — a minimum, not a schedule.
          required: false
          schema:
            type: integer
            example: 1
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            alreadyExists:
              summary: A list with this identifier is already published (do not retry)
              value:
                error: "status_list_already_exists"
                error_description: "Status list already exists"
            writeContention:
              summary: Rolled back by a storage lock race (retry unchanged)
              value:
                error: "write_contention"
                error_description: "The write lost a lock race in storage and was rolled back. Nothing was modified; retry the same request."

    CredentialConflict:
      description: |
        The credential registration was rejected. Read the `error` field.

        `credentials_already_exist` — this issuer already has credentials
        registered. **Retrying will never succeed.**

        `write_contention` — the write lost a lock race inside the database
        (deadlock or lock-wait timeout) and was rolled back. Nothing was created,
        so **retry the identical request** after the `Retry-After` interval plus
        jitter.
      headers:
        Retry-After:
          description: |
            Present only for `write_contention`. Seconds to wait before
            retrying — a minimum, not a schedule.
          required: false
          schema:
            type: integer
            example: 1
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            alreadyExists:
              summary: This issuer is already registered (do not retry)
              value:
                error: "credentials_already_exist"
                error_description: "Credentials already exist for this issuer"
            writeContention:
              summary: Rolled back by a storage lock race (retry unchanged)
              value:
                error: "write_contention"
                error_description: "The write lost a lock race in storage and was rolled back. Nothing was modified; retry the same request."

    PayloadTooLarge:
      description: |
        The request body exceeds the operator-configurable
        `limits.max_body_size_bytes` (default 2 MiB). Rejected by the
        `RequestBodyLimitLayer` before the handler runs.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            error: "payload_too_large"
            error_description: "The request body exceeds the configured maximum size"

    UnprocessableEntity:
      description: |
        The request was well-formed but the resulting serialized status list
        exceeds the operator-configurable `limits.max_serialized_list_size`
        (default 1 MiB), or (for `POST /api/v1/credentials`) the supplied
        public key could not be parsed into a JWK.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            error: "status_too_large"
            error_description: "Serialized status list size exceeds the configured maximum"

    TooManyRequests:
      description: |
        The client has exceeded the configured rate-limit quota for the route
        tier (strict, per-issuer, or permissive — see the Rate limiting section
        in the API description).
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            error: "too_many_requests"
            error_description: "Too many requests"

    UpdateConflict:
      description: |
        The write was rejected because it raced another writer. Two distinct
        cases share this status and they require **opposite** client behaviour,
        so branch on the `error` field rather than on the status code.

        `update_conflict` — optimistic-concurrency conflict. Another writer's
        update landed first between the client's read and this write, so this
        request was rejected rather than silently overwriting it. The client's
        view is stale: **re-read the current state before retrying**, because
        replaying the same request would reapply it to a changed list.

        `write_contention` — the write lost a lock race inside the database
        (deadlock or lock-wait timeout) and was rolled back by the server.
        Nothing was modified and no writer won, so **retry the identical
        request**; no re-read is required. A `Retry-After` header gives a floor —
        add jitter on top, since the writers that just collided would otherwise
        resynchronise.

        > Note for integrators: 409 is not a status most generic HTTP clients,
        > SDKs or service meshes retry automatically. `write_contention` is
        > transient and safe to replay, but recovering from it requires handling
        > this code explicitly.
      headers:
        Retry-After:
          description: |
            Present only for `write_contention`. Seconds to wait before
            retrying — a minimum, not a schedule.
          required: false
          schema:
            type: integer
            example: 1
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            updateConflict:
              summary: A racing writer's update landed first (re-read, then retry)
              value:
                error: "update_conflict"
                error_description: "The status list was modified concurrently"
            writeContention:
              summary: Rolled back by a storage lock race (retry unchanged)
              value:
                error: "write_contention"
                error_description: "The write lost a lock race in storage and was rolled back. Nothing was modified; retry the same request."

    UpdateInternalServerError:
      description: |
        Internal server error. The status list row and the historical snapshot
        recording the change are written in a single database transaction, so a
        500 from this endpoint means **no partial write occurred**: the list is
        unchanged, no snapshot was recorded, and the previous state remains
        authoritative. The request is therefore safe to retry as-is.

        This differs from a `409`, which means the write was rejected because it
        raced another writer. A `409 update_conflict` requires re-reading the
        current state before retrying; a `409 write_contention` and a `500` do
        not — both are safe to replay as-is.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            error: "internal_error"
            error_description: "The server encountered an unexpected error."

    ServiceUnavailable:
      description: Service temporarily unavailable
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            error: "service_unavailable"
            error_description: "the service is currently unavailable. Please try again later"

    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            error: "internal_error"
            error_description: "The server encountered an unexpected error."