raises error when ratelimit exceeded (#71)

* fixes #11

* moves RatelimitError into namespace of other errors

* adds docs

Author: simonneutert

.rubocop.yml

@@ -22,3 +22,7 @@ Metrics:
 
 Layout/LineLength:
   Max: 256
+
+Style/MultilineBlockChain:
+  Exclude:
+    - spec/**/*

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 * [#62](https://github.com/dblock/strava-ruby-client/pull/68): Drops `Activity#type` attribute as it is being deprecated by Strava, dropping `Activity#type_emoji` with it - [@simonneutert](https://github.com/simonneutert).
 * [#23](https://github.com/dblock/strava-ruby-client/pull/23): Failed uploads raise Strava::Errors::UploadError - [@ylecuyer](https://github.com/ylecuyer), [@simonneutert](https://github.com/simonneutert).
+* [#69](https://github.com/dblock/strava-ruby-client/pull/69): Raises `Strava::Api::RatelimitError`, when API ratelimit exceeded - [@simonneutert](https://github.com/simonneutert).
 * Your contribution here.
 
 ### 1.0.0 (2022/12/29)

README.md

@@ -64,6 +64,7 @@ Unlike other clients, including [strava-api-v3](https://github.com/jaredholdcrof
     - [Command Line OAuth Workflow](#command-line-oauth-workflow)
   - [Webhooks](#webhooks)
   - [Ratelimit](#ratelimit)
+    - [Exceeded Ratelimit](#exceeded-ratelimit)
 - [Configuration](#configuration)
   - [Web Client Options](#web-client-options)
   - [API Client Options](#api-client-options)
@@ -969,6 +970,16 @@ You can access the Hash containing all limits by calling `to_h`.
 }
 ```
 
+#### Exceeded Ratelimit
+
+Strava answers with HTTP status code 429, when ratelimits are exceeded. This will in return raise `Strava::Errors::RatelimitError`.
+
+```ruby
+error.is_a?(Strava::Errors::RatelimitError) #=> true
+error.ratelimit.is_a?(Strava::Api::Ratelimit) #=> true
+# see Strava::Api::Ratelimit
+```
+
 ## Configuration
 
 ### Web Client Options

UPGRADING.md

@@ -4,6 +4,7 @@
 
 - Dropping `Activity` attribute `type` and `type_emoji` in favor of `sport_type` and `sport_type_emoji`. Creating or updating an `Activity` requires you to use `sport_type` instead of `type`, as refered in the [README](README.md#create-an-activity). For details visit the official [Strava docs: Create Activity](https://developers.strava.com/docs/reference/#api-Activities-createActivity) and the entry from June 15, 2022 in [Strava's V3 API Changelog](https://developers.strava.com/docs/changelog/).
 - Uploading a file using `create_upload` requires you to check its process, using `client.updload('your-unique-upload-id')`. A successful upload does just mean, that the file was accepted. The Processing of the file is an independent process on Strava's side. From now on, `client.updload('your-unique-upload-id')` will raise `Strava::Errors::UploadError`, if Strava failed processing the file, e.g. it being a duplicate.
+- Exceeded Ratelimits (HTTP Status: 429) do now raise a customized Error `Strava::Errors::RatelimitError`. You can use the `Strava::Api::Ratelimit` object coming with the error, for further inspection of your current ratelimits.
 
 ### Upgrading to >= 1.0.0
 

lib/strava-ruby-client.rb

@@ -18,6 +18,7 @@
 
 require_relative 'strava/errors/fault'
 require_relative 'strava/errors/upload_error'
+require_relative 'strava/errors/ratelimit_error'
 
 require_relative 'strava/models/mixins/time'
 require_relative 'strava/models/mixins/distance'

lib/strava/api/ratelimit.rb

@@ -9,6 +9,20 @@ def initialize(response)
         @body = response.body
       end
 
+      def exceeded
+        return false unless limit?
+
+        @exceeded ||= if fifteen_minutes_remaining && fifteen_minutes_remaining <= 0
+                        { fifteen_minutes_remaining: fifteen_minutes_remaining }
+                      elsif total_day_remaining && total_day_remaining <= 0
+                        { total_day_remaining: total_day_remaining }
+                      end
+      end
+
+      def exceeded?
+        !!exceeded
+      end
+
       def to_s
         to_h.map do |k, v|
           "#{k}: #{v}"

lib/strava/errors/ratelimit_error.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Strava
+  module Errors
+    class RatelimitError < ::Faraday::ClientError
+      attr_reader :http_response, :ratelimit, :error_message
+
+      def initialize(http_response, error_message = nil)
+        @response = http_response.response
+        @ratelimit = Strava::Api::Ratelimit.new(@response)
+        @error_message = error_message || message
+        super({
+          status: http_response.status,
+          headers: http_response.response_headers,
+          body: http_response.body
+        })
+      end
+
+      def message
+        response[:body]['message'] || super
+      end
+
+      def headers
+        response[:headers]
+      end
+
+      def errors
+        response[:body]['errors']
+      end
+    end
+  end
+end

lib/strava/web/raise_response_error.rb

@@ -12,6 +12,8 @@ def on_complete(env)
         when 407
           # mimic the behavior that we get with proxy requests with HTTPS
           raise Faraday::ConnectionFailed, %(407 "Proxy Authentication Required ")
+        when 429
+          raise Strava::Errors::RatelimitError.new(env, 'Too Many Requests')
         when CLIENT_ERROR_STATUSES
           raise Strava::Errors::Fault, response_values(env)
         end