The iPhone's Mail app connects to Google Gmail -- and it's paid version, Google Accounts -- via the IMAP protocol [Wikipedia link]. Until Apple and/or Google get off their duffs and provide built-in push Gmail (or absent that, Google Sync Gmail for those not otherwise using their single Exchange ActiveSync slot), IMAP is all we have. (And IMAP IDLE may be what we have for push Gmail as well...) So what's the problem?
Gmail was born of and for the Web, and admittedly Gmail for the iPhone's Mobile Safari web browser is among the very best WebApps on any platform. However, many people still use, and even prefer to use, local clients like the iPhone's Mail app, and for that or any local client, Google's IMAP implementation has always been a second-class citizen.
Forgetting for now for the mapping of labels to folders results in multiple copies of the same email being stored on the local side, one of the major issues with Google's IMAP implementation is their ludicrous 10 simultaneous connection limit. This might not seem particularly strict, but given that every client can and does typically open multiple connections and having your iPhone, desktop, and laptop all open at the same time can cause Gmail to error out.
On a daily basis, users have to carry the mental overhead of carefully and conscientiously closing email clients on one machine before turning on another, or enabling or disabling a VPN connection (which then treats the mail client as a new set of connections).
By contrast, MobileMe and Exchange/ActiveSync have no problem with this usage pattern. Add to this random "invalid certificate", "unable to find mailbox: inbox", "over capacity", and other errors, and the state of Google's IMAP implementation is really called into question.
For iPhone Gmail users, the lack of quality error messages (likely something that needs improving on Apple's side) makes it particularly frustrating, as many of the different problems listed above simply result in an "incorrect password" pop-up box. (See image at the top of this post).
Personally -- and I'm not alone in this -- I've pretty much abandoned front-facing Gmail. I still use the unmatched excellence of Gmail's server-side filters, but then forward the mail itself to MobileMe. (The irony of the once-plagued MobileMe service now proving more robust over IMAP than Gmail isn't lost on me and should be lost on Google).
For those who maintain Gmail is free and we shouldn't complain, Google Accounts -- which is paid for -- exhibits the exact same problems on a regular basis.
Gmail is arguably the best webmail on the internet. It could easily be the best email period. Google's finally taken the humorously long-standing "beta" tag off the service. It's gone prime time. It's time to make the IMAP implementation live up to that level of standard.