OneSignal · sherwinski · Jun 18, 2026 · Jun 17, 2026
diff --git a/README.md b/README.md
@@ -4,15 +4,15 @@ OneSignal - the Ruby gem for OneSignal
 
 A powerful way to send personalized messages at scale and build effective customer engagement strategies. Learn more at onesignal.com
 
-- API version: 5.6.0
-- Package version: 5.6.0
+- API version: 5.7.0
+- Package version: 5.7.0
 
 ## Installation
 
 Add to your `Gemfile`:
 
 ```ruby
-gem 'onesignal', '~> 5.6.0'
+gem 'onesignal', '~> 5.7.0'
 ```
 
 Then run `bundle install`.

diff --git a/docs/DefaultApi.md b/docs/DefaultApi.md
diff --git a/lib/onesignal.rb b/lib/onesignal.rb
@@ -3,7 +3,7 @@
 
 #A powerful way to send personalized messages at scale and build effective customer engagement strategies. Learn more at onesignal.com
 
-The version of the OpenAPI document: 5.6.0
+The version of the OpenAPI document: 5.7.0
 Contact: devrel@onesignal.com
 Generated by: https://openapi-generator.tech
 OpenAPI Generator version: 6.0.0-SNAPSHOT
@@ -15,6 +15,7 @@
 require 'onesignal/api_error'
 require 'onesignal/version'
 require 'onesignal/configuration'
+require 'onesignal/helpers'
 
 # Models
 require 'onesignal/models/api_key_token'
@@ -105,3 +106,4 @@ def configure
     end
   end
 end
+require 'onesignal/errors'
diff --git a/lib/onesignal/api/default_api.rb b/lib/onesignal/api/default_api.rb
@@ -3,7 +3,7 @@
 
 #A powerful way to send personalized messages at scale and build effective customer engagement strategies. Learn more at onesignal.com
 
-The version of the OpenAPI document: 5.6.0
+The version of the OpenAPI document: 5.7.0
 Contact: devrel@onesignal.com
 Generated by: https://openapi-generator.tech
 OpenAPI Generator version: 6.0.0-SNAPSHOT

diff --git a/lib/onesignal/api_client.rb b/lib/onesignal/api_client.rb
@@ -3,7 +3,7 @@
 
 #A powerful way to send personalized messages at scale and build effective customer engagement strategies. Learn more at onesignal.com
 
-The version of the OpenAPI document: 5.6.0
+The version of the OpenAPI document: 5.7.0
 Contact: devrel@onesignal.com
 Generated by: https://openapi-generator.tech
 OpenAPI Generator version: 6.0.0-SNAPSHOT
@@ -90,7 +90,7 @@ def build_request(http_method, path, opts = {})
       url = build_request_url(path, opts)
       http_method = http_method.to_sym.downcase
 
-      opts[:header_params]['OS-Usage-Data'] = 'kind=sdk, sdk-name=onesignal-ruby, version=5.6.0'
+      opts[:header_params]['OS-Usage-Data'] = 'kind=sdk, sdk-name=onesignal-ruby, version=5.7.0'
       header_params = @default_headers.merge(opts[:header_params] || {})
       query_params = opts[:query_params] || {}
       form_params = opts[:form_params] || {}

diff --git a/lib/onesignal/api_error.rb b/lib/onesignal/api_error.rb
@@ -3,13 +3,15 @@
 
 #A powerful way to send personalized messages at scale and build effective customer engagement strategies. Learn more at onesignal.com
 
-The version of the OpenAPI document: 5.6.0
+The version of the OpenAPI document: 5.7.0
 Contact: devrel@onesignal.com
 Generated by: https://openapi-generator.tech
 OpenAPI Generator version: 6.0.0-SNAPSHOT
 
 =end
 
+require 'json'
+
 module OneSignal
   class ApiError < StandardError
     attr_reader :code, :response_headers, :response_body
@@ -53,5 +55,52 @@ def message
 
       msg
     end
+
+    # The error messages carried by the response body, normalized to a flat
+    # Array<String> regardless of which envelope shape the API returned
+    # (`{ errors: "..." }`, `{ errors: ["..."] }`, `{ errors: [{ code:, title: }] }`,
+    # or an object map such as `{ errors: { invalid_aliases: {...} } }`, surfaced
+    # as `"<key>: <value>"` entries). Returns an empty array when the body is not
+    # a recognizable error envelope. The raw body remains on +response_body+.
+    #
+    # @return [Array<String>]
+    def error_messages
+      parsed = if response_body.is_a?(String)
+                 begin
+                   JSON.parse(response_body)
+                 rescue JSON::ParserError, TypeError
+                   nil
+                 end
+               else
+                 response_body
+               end
+      return [] unless parsed.is_a?(Hash)
+
+      errors = parsed['errors'] || parsed[:errors]
+      case errors
+      when String
+        [errors]
+      when Array
+        errors.map do |e|
+          if e.is_a?(String)
+            e
+          elsif e.is_a?(Hash)
+            title = e['title'] || e[:title]
+            title = nil if title == ''
+            title || e['code'] || e[:code]
+          end
+        end.compact
+      when Hash
+        # Object-shaped envelopes (e.g. { invalid_aliases: {...} }) carry data
+        # under arbitrary keys; surface each so it isn't silently dropped. Key
+        # order is unspecified, so sort for deterministic output.
+        errors.map do |key, value|
+          rendered = value.is_a?(String) ? value : value.to_json
+          "#{key}: #{rendered}"
+        end.sort
+      else
+        []
+      end
+    end
   end
 end
diff --git a/lib/onesignal/configuration.rb b/lib/onesignal/configuration.rb
@@ -3,7 +3,7 @@
 
 #A powerful way to send personalized messages at scale and build effective customer engagement strategies. Learn more at onesignal.com
 
-The version of the OpenAPI document: 5.6.0
+The version of the OpenAPI document: 5.7.0
 Contact: devrel@onesignal.com
 Generated by: https://openapi-generator.tech
 OpenAPI Generator version: 6.0.0-SNAPSHOT

diff --git a/lib/onesignal/errors.rb b/lib/onesignal/errors.rb
@@ -0,0 +1,23 @@
+# Generated from inputs/api/error-catalog.json. Do not edit by hand.
+
+module OneSignal
+  # Sentinel error message strings the OneSignal API can return. Each
+  # constant equals the literal message the server emits, so you can test
+  # membership against ApiError#error_messages (e.g. NO_TARGETING_SPECIFIED).
+  #
+  # Note: 200-status sentinels such as NO_SUBSCRIBERS arrive on a successful
+  # response, not via the exception accessor — read the response's errors
+  # field for those.
+  module Errors
+    # HTTP 403 | retryable: no | emitted by: any API-key-authenticated endpoint (REST or Organization key) | note: Generic auth-failure message the public api.onesignal.com edge returns for any invalid or mismatched key — REST or Organization — so a single sentinel covers both. Supersedes the Rails-monolith INVALID_REST_API_KEY / INVALID_USER_AUTH_KEY strings, which the public host no longer returns verbatim. Note the double space after 'denied.'
+    INVALID_API_KEY = 'Access denied.  Please include an \'Authorization: ...\' header with a valid API key (https://documentation.onesignal.com/docs/en/keys-and-ids#api-keys).'.freeze
+    # HTTP 400, 404 | retryable: no | emitted by: POST /notifications/{id}/history, POST /notifications/{id}/messages, GET /notifications/{id} (export) | note: Verified live 2026-06-16: GET /notifications/{bogus-uuid} returns 404 with this exact message.
+    NOTIFICATION_NOT_FOUND = 'Notification not found'.freeze
+    # HTTP 200 | retryable: no | emitted by: POST /notifications | note: Returned with HTTP 200 OK (id is empty), not an error status. The flagship case for the errorMessages accessor — lets callers distinguish a sent notification from a no-op without parsing the polymorphic 200 body.
+    NO_SUBSCRIBERS = 'All included players are not subscribed'.freeze
+    # HTTP 400 | retryable: no | emitted by: POST /notifications | note: Verified live 2026-06-16: a no-targeting POST /notifications returns 400 with this exact message.
+    NO_TARGETING_SPECIFIED = 'You must include which players, segments, or tags you wish to send this notification to.'.freeze
+    # HTTP 503 | retryable: yes | emitted by: any endpoint (pgbouncer rejection) | note: Transient DB/pgbouncer failure — the canonical retryable sentinel.
+    SERVICE_UNAVAILABLE = 'Service temporarily unavailable'.freeze
+  end
+end
diff --git a/lib/onesignal/helpers.rb b/lib/onesignal/helpers.rb
@@ -0,0 +1,92 @@
+require 'securerandom'
+
+module OneSignal
+  # Helpers for common OneSignal API usage patterns.
+  module Helpers
+    CreateNotificationWithRetryResult = Struct.new(:response, :was_replayed)
+
+    RETRYABLE_CODES = [429, 503].freeze
+    MIN_BASE_DELAY = 1.0
+    MAX_BASE_DELAY = 60.0
+
+    # Create a notification with safe, idempotent retries.
+    #
+    # Ensures +notification.idempotency_key+ is set (generating a UUIDv4 when
+    # absent) so the server can deduplicate, then calls +create_notification+.
+    # Transient failures (HTTP 429, HTTP 503, or connection-level errors) are
+    # retried up to +max_retries+ times with the SAME idempotency key,
+    # honoring the +Retry-After+ response header when present and falling back
+    # to exponential backoff (+base_delay * 2**attempt+ seconds) otherwise.
+    # Other errors are raised immediately.
+    #
+    # @param api [DefaultApi] the API instance to call through
+    # @param notification [Notification] an existing idempotency_key is
+    #   respected, never overwritten
+    # @param max_retries [Integer] retries after the initial attempt
+    # @param base_delay [Float] backoff base in seconds when Retry-After is
+    #   absent; clamped to [1.0, 60.0]
+    # @return [CreateNotificationWithRetryResult] +response+ holds the
+    #   CreateNotificationSuccessResponse; +was_replayed+ is true when the
+    #   server answered from a previously completed request, as signaled by
+    #   the +Idempotent-Replayed+ response header
+    def self.create_notification_with_retry(api, notification, max_retries: 3, base_delay: 1.0)
+      if notification.idempotency_key.nil? || notification.idempotency_key.to_s.empty?
+        notification.idempotency_key = SecureRandom.uuid
+      end
+
+      # Clamp the backoff base so a stray value can neither hammer the API
+      # (too small) nor stall the caller for an unbounded stretch (too large).
+      base_delay = [[base_delay, MIN_BASE_DELAY].max, MAX_BASE_DELAY].min
+
+      attempt = 0
+      begin
+        data, _status, headers = api.create_notification_with_http_info(notification)
+        CreateNotificationWithRetryResult.new(data, replayed?(headers))
+      rescue ApiError => e
+        # code nil/0 covers connection timeouts and libcurl-level failures.
+        retryable = e.code.nil? || e.code.zero? || RETRYABLE_CODES.include?(e.code)
+        raise if !retryable || attempt >= max_retries
+
+        delay = retry_delay(e.response_headers, attempt, base_delay)
+        sleep(delay) if delay > 0
+        attempt += 1
+        retry
+      end
+    end
+
+    def self.header_value(headers, name)
+      return nil unless headers.respond_to?(:each_pair)
+
+      headers.each_pair do |key, value|
+        return value if key.to_s.downcase == name
+      end
+      nil
+    end
+    private_class_method :header_value
+
+    def self.replayed?(headers)
+      header_value(headers, 'idempotent-replayed').to_s.strip.downcase == 'true'
+    end
+    private_class_method :replayed?
+
+    def self.retry_delay(headers, attempt, base_delay)
+      retry_after = header_value(headers, 'retry-after')
+      if retry_after && retry_after.to_s.strip.match?(/\A\d+(\.\d+)?\z/)
+        return retry_after.to_f
+      end
+
+      base_delay * (2**attempt)
+    end
+    private_class_method :retry_delay
+  end
+
+  # Surface the idempotent-retry helper as an instance method so the call
+  # mirrors +create_notification+. Delegates to Helpers (single source of
+  # truth); reopening is load-order independent since the body runs at call
+  # time. See Helpers.create_notification_with_retry for the full contract.
+  class DefaultApi
+    def create_notification_with_retry(notification, max_retries: 3, base_delay: 1.0)
+      Helpers.create_notification_with_retry(self, notification, max_retries: max_retries, base_delay: base_delay)
+    end
+  end
+end
diff --git a/lib/onesignal/models/api_key_token.rb b/lib/onesignal/models/api_key_token.rb
@@ -3,7 +3,7 @@
 
 #A powerful way to send personalized messages at scale and build effective customer engagement strategies. Learn more at onesignal.com
 
-The version of the OpenAPI document: 5.6.0
+The version of the OpenAPI document: 5.7.0
 Contact: devrel@onesignal.com
 Generated by: https://openapi-generator.tech
 OpenAPI Generator version: 6.0.0-SNAPSHOT

diff --git a/lib/onesignal/models/api_key_tokens_list_response.rb b/lib/onesignal/models/api_key_tokens_list_response.rb
@@ -3,7 +3,7 @@
 
 #A powerful way to send personalized messages at scale and build effective customer engagement strategies. Learn more at onesignal.com
 
-The version of the OpenAPI document: 5.6.0
+The version of the OpenAPI document: 5.7.0
 Contact: devrel@onesignal.com
 Generated by: https://openapi-generator.tech
 OpenAPI Generator version: 6.0.0-SNAPSHOT

diff --git a/lib/onesignal/models/app.rb b/lib/onesignal/models/app.rb
@@ -3,7 +3,7 @@
 
 #A powerful way to send personalized messages at scale and build effective customer engagement strategies. Learn more at onesignal.com
 
-The version of the OpenAPI document: 5.6.0
+The version of the OpenAPI document: 5.7.0
 Contact: devrel@onesignal.com
 Generated by: https://openapi-generator.tech
 OpenAPI Generator version: 6.0.0-SNAPSHOT

diff --git a/lib/onesignal/models/basic_notification.rb b/lib/onesignal/models/basic_notification.rb
@@ -3,7 +3,7 @@
 
 #A powerful way to send personalized messages at scale and build effective customer engagement strategies. Learn more at onesignal.com
 
-The version of the OpenAPI document: 5.6.0
+The version of the OpenAPI document: 5.7.0
 Contact: devrel@onesignal.com
 Generated by: https://openapi-generator.tech
 OpenAPI Generator version: 6.0.0-SNAPSHOT

diff --git a/lib/onesignal/models/basic_notification_all_of.rb b/lib/onesignal/models/basic_notification_all_of.rb
@@ -3,7 +3,7 @@
 
 #A powerful way to send personalized messages at scale and build effective customer engagement strategies. Learn more at onesignal.com
 
-The version of the OpenAPI document: 5.6.0
+The version of the OpenAPI document: 5.7.0
 Contact: devrel@onesignal.com
 Generated by: https://openapi-generator.tech
 OpenAPI Generator version: 6.0.0-SNAPSHOT

diff --git a/lib/onesignal/models/basic_notification_all_of_android_background_layout.rb b/lib/onesignal/models/basic_notification_all_of_android_background_layout.rb
@@ -3,7 +3,7 @@
 
 #A powerful way to send personalized messages at scale and build effective customer engagement strategies. Learn more at onesignal.com
 
-The version of the OpenAPI document: 5.6.0
+The version of the OpenAPI document: 5.7.0
 Contact: devrel@onesignal.com
 Generated by: https://openapi-generator.tech
 OpenAPI Generator version: 6.0.0-SNAPSHOT

diff --git a/lib/onesignal/models/button.rb b/lib/onesignal/models/button.rb
@@ -3,7 +3,7 @@
 
 #A powerful way to send personalized messages at scale and build effective customer engagement strategies. Learn more at onesignal.com
 
-The version of the OpenAPI document: 5.6.0
+The version of the OpenAPI document: 5.7.0
 Contact: devrel@onesignal.com
 Generated by: https://openapi-generator.tech
 OpenAPI Generator version: 6.0.0-SNAPSHOT

diff --git a/lib/onesignal/models/copy_template_request.rb b/lib/onesignal/models/copy_template_request.rb
@@ -3,7 +3,7 @@
 
 #A powerful way to send personalized messages at scale and build effective customer engagement strategies. Learn more at onesignal.com
 
-The version of the OpenAPI document: 5.6.0
+The version of the OpenAPI document: 5.7.0
 Contact: devrel@onesignal.com
 Generated by: https://openapi-generator.tech
 OpenAPI Generator version: 6.0.0-SNAPSHOT

diff --git a/lib/onesignal/models/create_api_key_request.rb b/lib/onesignal/models/create_api_key_request.rb
@@ -3,7 +3,7 @@
 
 #A powerful way to send personalized messages at scale and build effective customer engagement strategies. Learn more at onesignal.com
 
-The version of the OpenAPI document: 5.6.0
+The version of the OpenAPI document: 5.7.0
 Contact: devrel@onesignal.com
 Generated by: https://openapi-generator.tech
 OpenAPI Generator version: 6.0.0-SNAPSHOT

diff --git a/lib/onesignal/models/create_api_key_response.rb b/lib/onesignal/models/create_api_key_response.rb
@@ -3,7 +3,7 @@
 
 #A powerful way to send personalized messages at scale and build effective customer engagement strategies. Learn more at onesignal.com
 
-The version of the OpenAPI document: 5.6.0
+The version of the OpenAPI document: 5.7.0
 Contact: devrel@onesignal.com
 Generated by: https://openapi-generator.tech
 OpenAPI Generator version: 6.0.0-SNAPSHOT

diff --git a/lib/onesignal/models/create_notification_success_response.rb b/lib/onesignal/models/create_notification_success_response.rb
@@ -3,7 +3,7 @@
 
 #A powerful way to send personalized messages at scale and build effective customer engagement strategies. Learn more at onesignal.com
 
-The version of the OpenAPI document: 5.6.0
+The version of the OpenAPI document: 5.7.0
 Contact: devrel@onesignal.com
 Generated by: https://openapi-generator.tech
 OpenAPI Generator version: 6.0.0-SNAPSHOT

diff --git a/lib/onesignal/models/create_segment_conflict_response.rb b/lib/onesignal/models/create_segment_conflict_response.rb
@@ -3,7 +3,7 @@
 
 #A powerful way to send personalized messages at scale and build effective customer engagement strategies. Learn more at onesignal.com
 
-The version of the OpenAPI document: 5.6.0
+The version of the OpenAPI document: 5.7.0
 Contact: devrel@onesignal.com
 Generated by: https://openapi-generator.tech
 OpenAPI Generator version: 6.0.0-SNAPSHOT

diff --git a/lib/onesignal/models/create_segment_success_response.rb b/lib/onesignal/models/create_segment_success_response.rb
@@ -3,7 +3,7 @@
 
 #A powerful way to send personalized messages at scale and build effective customer engagement strategies. Learn more at onesignal.com
 
-The version of the OpenAPI document: 5.6.0
+The version of the OpenAPI document: 5.7.0
 Contact: devrel@onesignal.com
 Generated by: https://openapi-generator.tech
 OpenAPI Generator version: 6.0.0-SNAPSHOT

diff --git a/lib/onesignal/models/create_template_request.rb b/lib/onesignal/models/create_template_request.rb
@@ -3,7 +3,7 @@
 
 #A powerful way to send personalized messages at scale and build effective customer engagement strategies. Learn more at onesignal.com
 
-The version of the OpenAPI document: 5.6.0
+The version of the OpenAPI document: 5.7.0
 Contact: devrel@onesignal.com
 Generated by: https://openapi-generator.tech
 OpenAPI Generator version: 6.0.0-SNAPSHOT

diff --git a/lib/onesignal/models/create_user_conflict_response.rb b/lib/onesignal/models/create_user_conflict_response.rb
@@ -3,7 +3,7 @@
 
 #A powerful way to send personalized messages at scale and build effective customer engagement strategies. Learn more at onesignal.com
 
-The version of the OpenAPI document: 5.6.0
+The version of the OpenAPI document: 5.7.0
 Contact: devrel@onesignal.com
 Generated by: https://openapi-generator.tech
 OpenAPI Generator version: 6.0.0-SNAPSHOT