Feature request: Better handle API errors

[nolessafool]

- What is the current behavior?

Currently if Netlify's API returns an HTTP error (4xx/5xx) status code during an action, we show the error but it's not usually very actionable:

$ netlify deploy --dir dist/ -a $NETLIFY_TOKEN -s $NETLIFY_SITE_ID --prod
Deploy path: [redacted]
Deploying to live site URL...
- Hashing files...
✔ Finished hashing 3222 files
- CDN diffing files...
 ›   Warning: TextHTTPError: 502
 ›   Warning: 
 ›   TextHTTPError: Bad Gateway
 ›
TextHTTPError: Bad Gateway
    at NetlifyAPI.createSiteDeploy ([redacted])
    at <anonymous>
error Command failed with exit code 2.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.

We saw the same thing for HTTP 429, though I think the root cause here has since been fixed:

$ netlify deploy --dir dist/ -a $NETLIFY_TOKEN -s $NETLIFY_SITE_ID_STAGING
Deploy path: [redacted]
Deploying to draft URL...
- Hashing files...
 Finished hashing 3181 files
- CDN diffing files...
 CDN requesting 2606 files
- Uploading 2606 files
› Warning: JSONHTTPError: Access Denied: bad return from the origin: 429 401
› Warning: 
› {
› "name": "JSONHTTPError",
› "status": 401,
› "json": {
› "code": 401,
› "message": "Access Denied: bad return from the origin: 429"
› }
› }
›

- If the current behavior is a bug, please provide the steps to reproduce.

@biilmann and @bcomnes were discussing this in this internal thread: https://netlify.slack.com/archives/CBC2U9MMG/p1551719842008700

- What is the expected behavior?

Errors have some obvious & actionable next steps, e.g. display a message like "wait 5 minutes and try again?", or "please contact support with information X/Y/Z for help" or better yet just magically retrying under the covers :)

This was observed with CLI version 2.8.1

[bcomnes]

or better yet just magically retrying under the covers :)

We retry two different ways under the covers: 429 backoff handling on all API requests, and exponential backoff for file uploading on all errors greater than 400.

We should add a CLI wrapper around the API client that looks for HTTP errors that pretty prints code, messages and some sane suggestions like you mentioned.

Thinking about this now would really clean up the command code as well, since we could assume a single place to handle API errors and eliminate so many try catch calls.

We could also expose a raw client if we wanted to do special error handling around errors.

[bcomnes]

This would be a good candidate for https://github.com/netlify/cli-utils