add specific error classes for Web API (#312)

Author: jmanian

.rubocop.yml

@@ -11,6 +11,7 @@ AllCops:
     - vendor/**/*
     - lib/slack/web/api/slack-api-ref/**/*
     - lib/slack/web/api/endpoints/* # Auto-generated
+    - lib/slack/web/api/errors.rb # Auto-generated
     - spec/slack/web/api/endpoints/* # Auto-generated
 Layout/EmptyLineAfterMagicComment:
   Enabled: false

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 * [#305](https://github.com/slack-ruby/slack-ruby-client/pull/305): Added `admin.inviteRequests.approve`, `admin.inviteRequests.deny`, `admin.inviteRequests.list`, `admin.inviteRequests.approved.list`, `admin.inviteRequests.denied.list`, `admin.teams.create`, `admin.teams.list`, `admin.teams.admins.list`, `admin.teams.owners.list`, `admin.teams.settings`, `admin.teams.settings.setIcon`, `admin.teams.settings.setName`, `admin.teams.settings.setDescription`, `admin.users.assign`, `admin.users.invite`, `admin.users.remove`, `admin.users.setAdmin`, `admin.users.setOwner` and `admin.users.setRegular` endpoints - [@manuelmeurer](https://github.com/manuelmeurer).
 * [#311](https://github.com/slack-ruby/slack-ruby-client/pull/311): Made Web API `response_metadata` more accessible in errors - [@jmanian](https://github.com/jmanian).
+* [#312](https://github.com/slack-ruby/slack-ruby-client/pull/312): Added specific error classes for Web API - [@jmanian](https://github.com/jmanian).
 * Your contribution here.
 
 ### 0.14.5 (2019/12/23)

README.md

@@ -32,6 +32,9 @@ A Ruby client for the Slack [Web](https://api.slack.com/web), [RealTime Messagin
     - [Web Client Options](#web-client-options)
     - [Pagination Support](#pagination-support)
     - [Error Handling](#error-handling)
+      - [Slack Errors](#slack-errors)
+      - [Rate Limiting](#rate-limiting)
+      - [Other Errors](#other-errors)
   - [RealTime Client](#realtime-client)
     - [Slack::RealTime::Stores::Store](#slackrealtimestoresstore)
     - [Slack::RealTime::Stores::Starter](#slackrealtimestoresstarter)
@@ -275,9 +278,33 @@ all_members # many thousands of team members retrieved 10 at a time
 
 #### Error Handling
 
-If a request fails, a `Slack::Web::Api::Errors::SlackError` will be raised. The error message contains the error code, which is also accessible with `slack_error.error`. In case of multiple errors, the error message contains the error codes separated by commas, or they are accessible as an array with `slack_error.errors`. The original response is also accessible using the `response` attribute. The `response_metadata` is accessible with `slack_error.response_metadata`.
+##### Slack Errors
 
-If you exceed [Slack’s rate limits](https://api.slack.com/docs/rate-limits), a `Slack::Web::Api::Errors::TooManyRequestsError` will be raised instead.
+If Slack returns an error for the request, then an error will be raised. The error class is specific to the type of error that Slack returns. For instance if Slack returns `account_inactive` then the error will be `Slack::Web::Api::Errors::AccountInactive`. This allows you to handle certain types of errors as needed:
+
+```ruby
+rescue Slack::Web::Api::Errors::AccountInactive => e
+  # deal with inactive account
+end
+```
+
+All of these errors inherit from `Slack::Web::Api::Errors::SlackError`, so you can handle or silence all errors if necessary:
+
+```ruby
+rescue Slack::Web::Api::Errors::SlackError => e
+  # capture all Slack errors
+end
+```
+
+If there's a new error type that is not yet known by this library, then it will raise `Slack::Web::Api::Errors::SlackError`. (Update the Web API if you find that errors are missing — see [CONTRIBUTING](CONTRIBUTING.md).)
+
+In all of these cases the error message contains the error code, which is also accessible with `slack_error.error`. In case of multiple errors, the error message contains the error codes separated by commas, or they are accessible as an array with `slack_error.errors`. The original response is also accessible using the `response` attribute. The `response_metadata` is accessible with `slack_error.response_metadata`.
+
+##### Rate Limiting
+
+If you exceed [Slack’s rate limits](https://api.slack.com/docs/rate-limits), a `Slack::Web::Api::Errors::TooManyRequestsError` will be raised instead. (This does not inherit from `Slack::Web::Api::Errors::SlackError`.)
+
+##### Other Errors
 
 In any other case, a `Faraday::ClientError` will be raised. This may be the case if Slack is temporarily unavailable, for example.
 

lib/slack-ruby-client.rb

@@ -27,6 +27,7 @@
 require_relative 'slack/web/api/errors/slack_error'
 require_relative 'slack/web/api/errors/too_many_requests_error'
 require_relative 'slack/web/api/error'
+require_relative 'slack/web/api/errors'
 require_relative 'slack/web/faraday/response/raise_error'
 require_relative 'slack/web/faraday/connection'
 require_relative 'slack/web/faraday/request'