Add example docs to APIError package

[tritone]

There are good examples for how to unpack and use APIError in the google-cloud-go docs. However, if a user looks up the APIError type directly, there is not any clarity on how to use it in the docs for the package, which might be confusing. We should add similar docs there, or maybe link to the google-cloud-go docs in question.

Alternatively (or additionally), it also might be worth added a section on error handling using APIError to the auto-generated doc.go files for GAPIC clients for easier discoverability.