I thought it was 4 Megabytes but I can see there are 8 Megabyte expansion cards. Is that the maximum? And is that an addressing/bank limit or a limit of the slot?
The largest amount of RAM supported by a real Apple IIgs is an 8MB expansion card, but that's somewhat misleading. The original IIgs came with 256KiB and the ROM3 came with 1MiB. A RAM expansion of 4MB will simply be added to these values. But when you have a card larger than 6MiB (which exists as well), you're going to see a problem: The extra RAM beyond 8MB is wasted/unused. It usually still needs to be there for the card to work properly, but your IIgs can't see it and can't use it.
You may have seen that IIgs emulators often allow you to have up to 14MiB of RAM, though doing so requires enabling an option for having more than 8MB. This is a hack, as it turns out, because the limit of 8MiB of RAM is actually in the ROM. As there are functionally two IIgs ROMs out there to worry about, the emulators simply patch them to accept more. This breaks a few titles, and only recently has the Apple // retro hardware market produced a ROM adapter board to use commodity chips to replace the mask ROMs of ROM0 machines with a burned ROM01 so that you need not cannibalize ROM01 machines to upgrade. (ROM0 is pain, you don't want it!)
In practice, a IIgs user will rarely need more than 4MiB of RAM. The ROM01 machine does not have enough RAM to effectively use GS/OS 6.0.x with 1.25MiB, but a basic configuration should work with the Apple 1MiB expansion card on a ROM03. (This is not my personal experience with an AppleTalk enabled system, however, I was getting $0201 errors--allocation failures--with the community 6.0.3 release on a 2MiB ROM3 system. A 4MiB card solved those problems.)
I'm sure means to utilize the full 8MiB possible on a standard IIgs, but without using RAMdisks in an era of flash drive expansion in the same price category, it feels like having 8MiB is more about bragging rights than anything. That's true in 2016 May, at least. If it changes in the future because 8MiB cards become standard, someone will comment to that effect. :)
With ROM hacking beginning in earnest on the Apple // series, it's likely the option to have more than 8MiB may happen in the future. If so, the hard limit would be 14MiB without bank switching as the upper 2MiB is used for ROM and the Mega II.
According to the Apple IIgs Hardware Reference, Second Edition, page 49:
The original Apple IIgs has 256K of RAM and 128K of ROM built in, and the 1 MB Apple IIgs has 1 MB RAM and 256K of ROM. This memory can be expanded to a total of 5 MB of RAM (4 MB RAM on a memory expansion card), and 1MB total ROM (768K ROM on a memory expansion card). Memory expansion of up to 8MB of RAM is possible by using the memory expansion slot, but complications requiring memory support logic keep this expansion from being practical. The ahrdware and firmware in the Apple IIgs are designed to support only a 5 MB maximum memory space. Addresses above 8 MB are not available to applications programs.
While the memory expansion slot has sufficient address lines available to decode addresses up to 8 MB, memory expansion cards of greater than 4 MB are not recommended. This is because memory expansion locations beyond 4 MB cannot be accessed via direct memory access (DMA), and also must provide on-board memory refresh support circuitry for the additional memory chips.
Since 8 MB expansion cards exist, it's clearly both possible and practical, but 8 MB does seem to be the upper limit due to the physical layout of the memory expansion slot.
The CPU in the IIgs can address up to 16 megabytes of memory. Due to lack of address lines on the CPU chip, the upper 8 bits is sent out on the data bus before each memory access and is latched by external circuitry in the CYA/FPI chip. These 8 bits are referred to as 'Bank address'. Ahead of a memory access, the CYA chip will manipulate the timing, address, and other signals on the main board to make it all work seamlessly; Fast, Slow, 8bit, 16 bit, DMA, slots, firmware, whatever.
In the IIgs firmware, the top 8M is 'reserved' for Rom, the bottom 8M for RAM. Deviating from this means you have to change firmware. (Rumor: If I recall correctly from a Kfest emulator discussion, there is a 1 byte patch for the memory manager to bring it up to 12M.)
The IIgs also uses some areas of the higher memory address area with dedicated RAM for 8 bit Apple II compatibility and video buffers that are timing dependant.
The IIgs memory expansion slot controlled by the CYA chip provides timing signals for refresh for up to 4 megabytes of additional memory. Bank addressing at the memory expansion slot is adjusted by the CYA/FPI chip so will differ from the CPU's bank addressing, offset b the number of banks built into the main board, 4 for Rom1, 16 for Rom3. So the memory accessed at the memory slot is at a different bank address range on a Rom1 vs a Rom3 and the CPU. If you go beyond 4 megabytes in the expansion slot you need extra circuitry to support refresh and DMA support is not going to work.
As stated earlier, above 8 megabytes total Ram would require patching firmware routines or using your own memory management.
Long story short: get up to 4M cheaply for best results, minimum 1M expansion to run it in IIgs mode vs Apple II mode.