components:
  schemas:
    ErrorMessage:
      type: object
      required:
        - message
      properties:
        message:
          type: string
          description: Human-readable error message
          example: Unauthorized

  responses:
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorMessage"
          example:
            message: phone is required

    Unauthorized:
      description: Missing or invalid session cookie
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorMessage"
          example:
            message: Unauthorized

    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorMessage"
          example:
            message: Session not found

    PayloadTooLarge:
      description: Uploaded file exceeds size limit (10 MB)
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorMessage"
          example:
            message: File too large

    ServiceUnavailable:
      description: Upstream core-api unavailable and dev mock disabled
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorMessage"
          example:
            message: Backend service unavailable
