scrapeunblocker 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e8096ca55e9f93c01077d947e60e36ec71c595e7ee92d1405a413a0746c303f0
-  data.tar.gz: 28c0667c78459edf026b26effd0209ea0635409eb078f152b8e4963be2312dd3
+  metadata.gz: f20529c692d1de01f3f02acca1accaf677cd5df2ec9d075bfb949b4b230272d2
+  data.tar.gz: b0eff5160bbd56e6e45700609ab17966d061d74537909c7a1a06df9242cddb7a
 SHA512:
-  metadata.gz: f1b51dee641104d7d77fd600c5cb2299f30d6dcdf3e155686befc2d3024c981fb0c904d2aa8d5d1f360797a9cdbd331356ec2c99f1a3832907704198689306c6
-  data.tar.gz: 8274485fa1644d6dfb1512bc33e93fc034f3c01a0248e450869315f3d0669244761ef146db9e11cac0ccfb3fe6361148d5b3ef64a4c706d967d825ef23fba9e6
+  metadata.gz: 2421c59b2bc7c32d769d01546b4f796b7f71237edf500af4ee21b56f0a1393532b6361cc4207264c6072c5510bd31dc840986adda94dfbc18e7d2fdbf03a1df8
+  data.tar.gz: 98532dd9a066ef4e52f1123a958e36f1f40df7f603a3055b78784337bedfb256a237343d011e086ba8d0feb94cd17100e2501d5317055b35bae15fc57bea27ea

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.9.0 (2026-10-07)
+
+- New `ScrapeUnblocker::BudgetExceededError` (a subclass of `PaymentRequiredError`): raised when the API answers 402 with `User set budget exceeded`, meaning this billing period's spend reached the monthly budget limit (EUR, excluding VAT) set in the [profile](https://app.scrapeunblocker.com/dashboard/profile). It clears at the start of the next billing period, or within about a minute after the limit is raised or removed. Like the other 402s it is never retried and not billed. Before, this body surfaced as a plain `PaymentRequiredError`.
+
+No breaking changes: `rescue ScrapeUnblocker::PaymentRequiredError` still catches it.
+
 ## 0.8.0 (2026-10-06)
 
 - `get_parsed` on a page that rendered but held no structured data now returns a normal `ParsedPage` instead of raising `NoDataExtractedError`. The API answers this case with a billed 200: `data` is empty, the new `data_extracted?` is `false`, the new `detail` explains it and the new `html` carries the rendered page, so no second call is needed. On a successful parse `data_extracted?` is `true` and `html` / `detail` are `nil`.

data/README.md

@@ -108,7 +108,6 @@ result["elements"].each { |el| p el }
 ```ruby
 result = su.get_parsed("https://www.walmart.com/ip/12345")
 puts result.page_type # e.g. "product"
-puts result.source    # how it was extracted
 p result.data         # the fields
 
 # If a parse ever comes back wrong, force a fresh set of rules:
@@ -259,7 +258,7 @@ begin
 rescue ScrapeUnblocker::BlockedError
   # 403: the target blocked every bypass path (not billed)
 rescue ScrapeUnblocker::PaymentRequiredError
-  # 402: quota, credit limit, or a failed payment - fix billing
+  # 402: quota, credit limit, your budget limit, or a failed payment - fix billing
 rescue ScrapeUnblocker::RateLimitError
   # 429: slow down
 rescue ScrapeUnblocker::UpstreamOutageError
@@ -272,9 +271,10 @@ end
 | `InvalidRequestError` | 400 | Bad URL, unsupported scheme, or the API key header was not sent |
 | `AuthenticationError` | 401 | Key not recognised - typo, stray whitespace, or a rotated key |
 | `NoSubscriptionError` | 401 | Key is fine, but the account has no active plan |
-| `PaymentRequiredError` | 402 | Billing block - base class for the three below |
+| `PaymentRequiredError` | 402 | Billing block - base class for the four below |
 | `QuotaExceededError` | 402 | The plan's requests for this period are used up |
 | `CreditLimitExceededError` | 402 | Unpaid balance is past the account's credit limit |
+| `BudgetExceededError` | 402 | This billing period's spend reached the monthly budget limit you set |
 | `PaymentFailedError` | 402 | A card payment was declined three times |
 | `BlockedError` | 403 | Blocked by bot protection on every path |
 | `NotFoundError` | 404 | What you asked for does not exist - no image on the page (`get_image`), or a plugin lookup found nothing |
@@ -323,7 +323,7 @@ Transient failures (429, 502, 503, 504 and network errors) are retried automatic
 
 ### Billing errors (402)
 
-The three billing blocks share a status code and differ only in their message, so the client raises a dedicated error for each:
+The four billing blocks share a status code and differ only in their message, so the client raises a dedicated error for each:
 
 ```ruby
 begin
@@ -332,12 +332,16 @@ rescue ScrapeUnblocker::QuotaExceededError
   # plan quota (plus any overage allowance) is used up for this period
 rescue ScrapeUnblocker::CreditLimitExceededError
   # unpaid balance passed the account credit limit
+rescue ScrapeUnblocker::BudgetExceededError
+  # this period's spend reached the monthly budget limit set in your profile
 rescue ScrapeUnblocker::PaymentFailedError
   # card declined three times - update the payment method
 end
 ```
 
-When more than one applies, the most serious wins: failed payment outranks credit limit, which outranks quota. All three lift by themselves once the billing state changes - access returns within about a minute, and the API key stays the same. One catch worth knowing: subscribing to a new plan does **not** clear `PaymentFailedError`, because the old unpaid invoice stays open until it is paid.
+When more than one applies, the most serious wins: failed payment outranks credit limit, which outranks quota, which outranks your own budget limit. All four lift by themselves once the billing state changes - access returns within about a minute, and the API key stays the same. One catch worth knowing: subscribing to a new plan does **not** clear `PaymentFailedError`, because the old unpaid invoice stays open until it is paid.
+
+`BudgetExceededError` (body `User set budget exceeded`) means this billing period's spend reached the monthly budget limit you set in your [profile](https://app.scrapeunblocker.com/dashboard/profile?utm_source=rubygems&utm_medium=integration&utm_campaign=ruby-sdk) (EUR, excluding VAT). The key works again at the start of the next billing period, or within about a minute after you raise or remove the limit.
 
 Full details for every status code: [docs.scrapeunblocker.com/errors](https://docs.scrapeunblocker.com/errors).
 

data/lib/scrapeunblocker/errors.rb

@@ -36,15 +36,16 @@ module ScrapeUnblocker
   # The account has a billing problem (HTTP 402).
   #
   # Credentials are fine - the request was stopped for a billing reason. There
-  # are three, each raised as a dedicated subclass: QuotaExceededError,
-  # CreditLimitExceededError and PaymentFailedError. Rescue this base class to
-  # handle all three.
+  # are four, each raised as a dedicated subclass: QuotaExceededError,
+  # CreditLimitExceededError, BudgetExceededError and PaymentFailedError.
+  # Rescue this base class to handle all four.
   #
   # When more than one applies, the most serious wins: failed payment outranks
-  # credit limit, which outranks quota. All three lift by themselves once the
-  # billing state changes - access returns within roughly a minute, with no key
-  # change needed. Like a 401, a 402 is refused before anything is scraped, so
-  # it is never billed. Retrying is pointless; fix the billing state first.
+  # credit limit, which outranks quota, which outranks your own budget limit.
+  # All four lift by themselves once the billing state changes - access returns
+  # within roughly a minute, with no key change needed. Like a 401, a 402 is
+  # refused before anything is scraped, so it is never billed. Retrying is
+  # pointless; fix the billing state first.
   class PaymentRequiredError < APIError; end
 
   # Every request the plan allows this period has been used (HTTP 402).
@@ -64,6 +65,17 @@ module ScrapeUnblocker
   # usually clears itself within about a minute.
   class CreditLimitExceededError < PaymentRequiredError; end
 
+  # This billing period's spend reached the monthly budget limit you set
+  # (HTTP 402).
+  #
+  # The limit is set in your profile (EUR, excluding VAT), and spend is counted
+  # the way the invoice is: the plan's fixed monthly fee, if any, plus the
+  # requests billed on top of it. Requests paid from coupon credit do not count.
+  # The key works again at the start of the next billing period, or within
+  # about a minute after you raise or remove the limit at
+  # https://app.scrapeunblocker.com/dashboard/profile.
+  class BudgetExceededError < PaymentRequiredError; end
+
   # A card payment has been declined three times (HTTP 402).
   #
   # Those attempts are the payment provider's automatic retries spread over
@@ -167,7 +179,7 @@ module ScrapeUnblocker
   BASE_MESSAGES = {
     400 => "Invalid request (bad URL, unsupported scheme, or missing API key header)",
     401 => "Authentication failed - key not recognised, or account has no active plan",
-    402 => "Billing block - quota exceeded, credit limit exceeded, or a failed payment",
+    402 => "Billing block - quota exceeded, credit limit exceeded, budget limit reached, or a failed payment",
     403 => "Target blocked by bot protection on every bypass path",
     404 => "Requested element not found on the page",
     408 => "Browser run timed out before the page was ready",
@@ -187,12 +199,13 @@ module ScrapeUnblocker
   end
   private_class_method :auth_error_class
 
-  # The three billing blocks share a status code and differ only in their
+  # The four billing blocks share a status code and differ only in their
   # plain-text body. An unrecognised body falls back to PaymentRequiredError.
   def self.billing_error_class(body)
     text = (body || "").downcase
     return QuotaExceededError if text.include?("quota exceeded")
     return CreditLimitExceededError if text.include?("credit limit exceeded")
+    return BudgetExceededError if text.include?("user set budget exceeded")
     return PaymentFailedError if text.include?("payment failed")
 
     PaymentRequiredError

data/lib/scrapeunblocker/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ScrapeUnblocker
-  VERSION = "0.8.0"
+  VERSION = "0.9.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: scrapeunblocker
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - ScrapeUnblocker
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-06 00:00:00.000000000 Z
+date: 2026-10-07 00:00:00.000000000 Z
 dependencies: []
 description: JS-rendered pages that bypass Cloudflare, DataDome, PerimeterX and Akamai,
   plus Google SERP and Skyscanner flights/hotels/car-hire scraping as JSON.