ipregistry 1.0.0

data/lib/ipregistry/cache.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Ipregistry
+  # Caching backends used by {Client} to memoize IP lookups.
+  #
+  # Only successful single and batch IP lookups are cached. Origin lookups are
+  # never cached, because the requester IP is only known from the response.
+  #
+  # A cache is any object responding to +get(key)+, +set(key, value)+,
+  # +delete(key)+, and +clear+, and safe for concurrent use from multiple
+  # threads — bring your own backend (Redis, Rails.cache, ...) by satisfying
+  # that interface.
+  module Cache
+    # The default cache: stores nothing, so lookups always hit the API and
+    # data is never stale.
+    class None
+      def get(_key) = nil
+
+      def set(_key, _value) = nil
+
+      def delete(_key) = nil
+
+      def clear = nil
+    end
+
+    # A thread-safe, in-process cache with time-based expiration and a bounded
+    # size using least-recently-used eviction.
+    #
+    #   cache = Ipregistry::Cache::Memory.new(max_size: 8192, ttl: 600)
+    #   client = Ipregistry::Client.new("YOUR_API_KEY", cache: cache)
+    class Memory
+      DEFAULT_MAX_SIZE = 4096
+      DEFAULT_TTL = 600 # seconds
+
+      # @param max_size [Integer] maximum number of entries held before the
+      #   least recently used entry is evicted (default 4096)
+      # @param ttl [Numeric] how long, in seconds, an entry stays valid after
+      #   being written (default 600)
+      # @param clock [#call] overridable monotonic clock, for testing
+      def initialize(max_size: DEFAULT_MAX_SIZE, ttl: DEFAULT_TTL,
+                     clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
+        raise ArgumentError, "max_size must be positive" unless max_size.positive?
+        raise ArgumentError, "ttl must be positive" unless ttl.positive?
+
+        @max_size = max_size
+        @ttl = ttl
+        @clock = clock
+        @mutex = Mutex.new
+        @entries = {} # key => [value, expires_at]; insertion order tracks recency
+      end
+
+      # Returns the cached value for key, or nil when absent or expired.
+      def get(key)
+        @mutex.synchronize do
+          value, expires_at = @entries[key]
+          next nil unless expires_at
+
+          if @clock.call > expires_at
+            @entries.delete(key)
+            next nil
+          end
+
+          # Re-insert to mark the entry as most recently used.
+          @entries.delete(key)
+          @entries[key] = [value, expires_at]
+          value
+        end
+      end
+
+      # Stores value under key, refreshing its expiration and evicting the
+      # least recently used entry if the cache is full.
+      def set(key, value)
+        @mutex.synchronize do
+          @entries.delete(key)
+          @entries[key] = [value, @clock.call + @ttl]
+          @entries.delete(@entries.each_key.first) while @entries.size > @max_size
+        end
+        nil
+      end
+
+      # Removes the entry for key, if present.
+      def delete(key)
+        @mutex.synchronize { @entries.delete(key) }
+        nil
+      end
+
+      # Removes every entry.
+      def clear
+        @mutex.synchronize { @entries.clear }
+        nil
+      end
+
+      # Current number of entries, including possibly stale ones. Primarily
+      # useful in tests.
+      def size
+        @mutex.synchronize { @entries.size }
+      end
+    end
+  end
+end

data/lib/ipregistry/client.rb

@@ -0,0 +1,424 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "openssl"
+require "uri"
+
+module Ipregistry
+  # Client for the Ipregistry API. A Client is safe for concurrent use by
+  # multiple threads.
+  #
+  #   client = Ipregistry::Client.new("YOUR_API_KEY")
+  #   info = client.lookup("8.8.8.8")
+  #   info.location.country.name # => "United States"
+  #
+  # By default the client uses a 15-second timeout, retries transient failures
+  # up to three times, and performs no caching. Behavior is customized with
+  # keyword arguments to {#initialize}.
+  class Client
+    # Base URL of the Ipregistry API used unless overridden with +base_url:+.
+    DEFAULT_BASE_URL = "https://api.ipregistry.co"
+
+    # Maximum number of IP addresses Ipregistry accepts in a single batch
+    # request. {#batch_lookup} transparently splits larger arrays into several
+    # requests so callers never have to.
+    MAX_BATCH_SIZE = 1024
+
+    DEFAULT_TIMEOUT = 15 # seconds
+    DEFAULT_MAX_RETRIES = 3
+    DEFAULT_RETRY_INTERVAL = 1.0 # seconds
+    DEFAULT_BATCH_CONCURRENCY = 4
+
+    # Default value of the User-Agent header sent with requests.
+    USER_AGENT = "IpregistryClient/Ruby/#{VERSION}".freeze
+
+    # Errors raised by Net::HTTP when a request does not complete in time.
+    TIMEOUT_ERRORS = [Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout].freeze
+    private_constant :TIMEOUT_ERRORS
+
+    # Errors raised by Net::HTTP for connection-level failures.
+    CONNECTION_ERRORS = [SocketError, SystemCallError, IOError, EOFError, OpenSSL::SSL::SSLError].freeze
+    private_constant :CONNECTION_ERRORS
+
+    # @return [Object] the cache used by the client
+    attr_reader :cache
+
+    # @return [String] the API base URL
+    attr_reader :base_url
+
+    # Creates a client authenticating with the given API key. You can obtain
+    # a key, along with a generous free tier, at https://ipregistry.co.
+    #
+    # @param api_key [String] your Ipregistry API key
+    # @param base_url [String] overrides the API base URL, mainly useful for
+    #   testing or pointing at a private deployment
+    # @param timeout [Numeric] per-request timeout in seconds, applied to
+    #   connection open, read, and write (default 15)
+    # @param max_retries [Integer] maximum number of automatic retries
+    #   performed in addition to the initial attempt; 0 disables retries
+    #   (default 3)
+    # @param retry_interval [Numeric] base backoff in seconds between retries;
+    #   successive retries use an exponentially increasing delay
+    #   (interval * 2^attempt), and a 429 response carrying a Retry-After
+    #   header takes precedence (default 1)
+    # @param retry_on_server_error [Boolean] whether 5xx responses are retried
+    #   (default true); transient network errors are always retried
+    # @param retry_on_too_many_requests [Boolean] whether 429 Too Many
+    #   Requests responses are retried, honoring the Retry-After header when
+    #   present. Ipregistry does not rate limit by default (it is opt-in per
+    #   API key), so this defaults to false
+    # @param cache [Object] response cache; disabled by default so that data
+    #   is never stale. Pass an {Cache::Memory} instance or any object with
+    #   the same interface
+    # @param max_batch_size [Integer] maximum number of IP addresses sent in a
+    #   single batch request, capped at {MAX_BATCH_SIZE} (the API limit)
+    # @param batch_concurrency [Integer] how many batch sub-requests
+    #   {#batch_lookup} dispatches concurrently when an array is large enough
+    #   to be split into chunks; 1 means strictly sequential dispatch, which
+    #   is gentler on a rate-limited API key (default 4)
+    # @param user_agent [String] overrides the User-Agent header sent with
+    #   requests
+    def initialize(api_key,
+                   base_url: DEFAULT_BASE_URL,
+                   timeout: DEFAULT_TIMEOUT,
+                   max_retries: DEFAULT_MAX_RETRIES,
+                   retry_interval: DEFAULT_RETRY_INTERVAL,
+                   retry_on_server_error: true,
+                   retry_on_too_many_requests: false,
+                   cache: Cache::None.new,
+                   max_batch_size: MAX_BATCH_SIZE,
+                   batch_concurrency: DEFAULT_BATCH_CONCURRENCY,
+                   user_agent: USER_AGENT)
+      raise ArgumentError, "api_key must not be nil or empty" if api_key.nil? || api_key.to_s.strip.empty?
+
+      @api_key = api_key.to_s
+      @base_url = base_url.to_s.sub(%r{/+\z}, "")
+      @timeout = timeout
+      @max_retries = [max_retries.to_i, 0].max
+      @retry_interval = retry_interval
+      @retry_on_server_error = retry_on_server_error
+      @retry_on_too_many_requests = retry_on_too_many_requests
+      @cache = cache || Cache::None.new
+      @max_batch_size = max_batch_size.to_i.clamp(1, MAX_BATCH_SIZE)
+      @batch_concurrency = [batch_concurrency.to_i, 1].max
+      @user_agent = user_agent
+    end
+
+    # Returns the data associated with the given IP address. The ip argument
+    # must be a non-empty IPv4 or IPv6 address (String or IPAddr); to look up
+    # the requester's own IP, use {#lookup_origin} instead.
+    #
+    # When a cache is configured, a hit is returned without contacting the
+    # API.
+    #
+    # @param ip [String, IPAddr] the IP address to look up
+    # @param fields [String, nil] restricts the response to the given fields,
+    #   using Ipregistry's field selector syntax (for example
+    #   "location.country.name,security"). This reduces payload size and, in
+    #   some cases, credit usage. See
+    #   https://ipregistry.co/docs/filtering-selecting-fields
+    # @param hostname [Boolean, nil] enables reverse-DNS hostname resolution
+    #   (disabled by default)
+    # @param params [Hash] arbitrary extra query parameters not covered by a
+    #   dedicated keyword
+    # @return [Models::IpInfo]
+    # @raise [ApiError, ClientError]
+    def lookup(ip, fields: nil, hostname: nil, **params)
+      ip = ip.to_s.strip
+      raise ArgumentError, "ip must not be empty; use #lookup_origin for the requester IP" if ip.empty?
+
+      query = build_query(fields: fields, hostname: hostname, **params)
+      key = cache_key(ip, query)
+      cached = @cache.get(key)
+      return cached if cached
+
+      info = Models::IpInfo.new(request_json(:get, url_for(ip, query)))
+      @cache.set(key, info)
+      info
+    end
+
+    # Returns the data associated with the IP address the request originates
+    # from, enriched with parsed User-Agent data. Origin lookups are never
+    # cached, because the requester IP is only known from the response.
+    #
+    # Accepts the same keywords as {#lookup}.
+    #
+    # @return [Models::RequesterIpInfo]
+    # @raise [ApiError, ClientError]
+    def lookup_origin(fields: nil, hostname: nil, **params)
+      query = build_query(fields: fields, hostname: hostname, **params)
+      Models::RequesterIpInfo.new(request_json(:get, url_for("", query)))
+    end
+
+    # Resolves several IP addresses at once. The returned {BatchResponse}
+    # preserves the order of ips, and each entry may independently succeed or
+    # fail; a raised error indicates the whole request failed (for example
+    # authentication or a network error), not the failure of an individual
+    # entry.
+    #
+    # The Ipregistry API accepts up to {MAX_BATCH_SIZE} addresses per request;
+    # larger arrays are transparently split into several requests dispatched
+    # with bounded concurrency (see +max_batch_size:+ and
+    # +batch_concurrency:+) and reassembled in input order.
+    #
+    # Entries already present in the cache are served locally; only the
+    # remainder are requested from the API, and freshly resolved entries are
+    # cached. Accepts the same keywords as {#lookup}.
+    #
+    # @param ips [Array<String, IPAddr>] the IP addresses to look up
+    # @return [BatchResponse]
+    # @raise [ApiError, ClientError]
+    def batch_lookup(ips, fields: nil, hostname: nil, **params)
+      ips = Array(ips).map { |ip| ip.to_s.strip }
+      query = build_query(fields: fields, hostname: hostname, **params)
+
+      cached = ips.map { |ip| @cache.get(cache_key(ip, query)) }
+      misses = ips.zip(cached).reject { |_, hit| hit }.map(&:first)
+      fresh = resolve_misses(misses, query)
+
+      BatchResponse.new(assemble_batch_results(ips, cached, fresh, query))
+    end
+
+    # Parses one or more raw User-Agent strings (such as the User-Agent
+    # header of an incoming HTTP request) into structured data. Results
+    # preserve the order of the input.
+    #
+    #   response = client.parse_user_agents("Mozilla/5.0 ...")
+    #   response[0].value!.name # => "Chrome"
+    #
+    # @param user_agents [Array<String>] the User-Agent strings to parse
+    # @return [BatchResponse]
+    # @raise [ApiError, ClientError]
+    def parse_user_agents(*user_agents)
+      body = JSON.generate(user_agents.flatten.map(&:to_s))
+      data = request_json(:post, "#{@base_url}/user_agent", body: body)
+      BatchResponse.new(parse_batch_results(data) { |entry| Models::UserAgent.new(entry) })
+    end
+
+    private
+
+    # Merges cached entries and freshly resolved results back into input
+    # order, caching newly successful entries along the way.
+    def assemble_batch_results(ips, cached, fresh, query)
+      next_fresh = -1
+      ips.each_with_index.map do |ip, i|
+        next BatchResponse::Result.success(cached[i]) if cached[i]
+
+        result = fresh[next_fresh += 1]
+        # Defensive: the API returned fewer results than requested.
+        result ||= BatchResponse::Result.failure(ApiError.new("missing result for requested IP address"))
+        @cache.set(cache_key(ip, query), result.value) if result.success?
+        result
+      end
+    end
+
+    # Fetches fresh data for the cache-missed IP addresses, splitting them
+    # into API-sized chunks dispatched with bounded concurrency when needed.
+    # The returned results preserve the order of misses.
+    def resolve_misses(misses, query)
+      return [] if misses.empty?
+
+      chunks = misses.each_slice(@max_batch_size).to_a
+      return batch_request(chunks.first, query) if chunks.size == 1
+
+      resolve_chunks(chunks, query).flatten(1)
+    end
+
+    # Dispatches batch chunks with at most batch_concurrency requests in
+    # flight and returns their results in order. If any chunk fails, the
+    # first error is raised once all in-flight requests have finished, and
+    # queued chunks are not started.
+    def resolve_chunks(chunks, query)
+      chunk_results = Array.new(chunks.size)
+      jobs = Queue.new
+      chunks.each_with_index { |chunk, index| jobs << [chunk, index] }
+      jobs.close
+
+      mutex = Mutex.new
+      first_error = nil
+
+      workers = Array.new([@batch_concurrency, chunks.size].min) do
+        Thread.new do
+          while (job = jobs.pop)
+            break if mutex.synchronize { first_error }
+
+            chunk, index = job
+            begin
+              chunk_results[index] = batch_request(chunk, query)
+            rescue Error => e
+              mutex.synchronize { first_error ||= e }
+            end
+          end
+        end
+      end
+      workers.each(&:join)
+
+      raise first_error if first_error
+
+      chunk_results
+    end
+
+    # Performs a single POST batch request and returns per-entry results.
+    def batch_request(ips, query)
+      data = request_json(:post, url_for("", query), body: JSON.generate(ips))
+      parse_batch_results(data) { |entry| Models::IpInfo.new(entry) }
+    end
+
+    # Maps the {"results" => [...]} envelope of a batch response to an array
+    # of Results, treating elements carrying an error code as failures.
+    def parse_batch_results(data)
+      entries = data.is_a?(Hash) && data["results"].is_a?(Array) ? data["results"] : []
+      entries.map do |entry|
+        if entry.is_a?(Hash) && entry["code"]
+          BatchResponse::Result.failure(ApiError.from_payload(entry))
+        else
+          BatchResponse::Result.success(yield(entry))
+        end
+      end
+    end
+
+    # Collapses lookup keywords into a deterministic, sorted query hash.
+    def build_query(fields:, hostname:, **params)
+      query = params.transform_keys(&:to_s)
+      query["fields"] = fields unless fields.nil?
+      query["hostname"] = hostname unless hostname.nil?
+      query.transform_values!(&:to_s)
+      query.sort.to_h
+    end
+
+    def url_for(ip, query)
+      url = "#{@base_url}/#{ip}"
+      url += "?#{URI.encode_www_form(query)}" unless query.empty?
+      url
+    end
+
+    # Derives a deterministic cache key from an IP address and its query
+    # parameters (already sorted by build_query).
+    def cache_key(ip, query)
+      return ip if query.empty?
+
+      "#{ip};#{URI.encode_www_form(query)}"
+    end
+
+    # Performs an HTTP request with automatic retries and returns the decoded
+    # 2xx response body. Non-2xx responses raise an {ApiError} subclass;
+    # transport and decoding failures raise a {ClientError} subclass.
+    def request_json(http_method, url, body: nil)
+      attempt = 0
+      loop do
+        response = attempt_request(http_method, url, body, attempt)
+
+        if response
+          status = response.code.to_i
+          return parse_json(response.body.to_s) if status.between?(200, 299)
+          raise api_error(response, status) unless retry_status?(status) && attempt < @max_retries
+
+          wait(backoff_delay(attempt, retry_after(response)))
+        else
+          # A transport error was swallowed by attempt_request: retry.
+          wait(backoff_delay(attempt, nil))
+        end
+
+        attempt += 1
+      end
+    end
+
+    # Performs one HTTP attempt. Transport errors are re-raised as typed
+    # ClientError subclasses once retries are exhausted, and otherwise
+    # swallowed (returning nil) so the caller backs off and retries;
+    # transient network errors are always retried, regardless of the
+    # retry-on-status flags.
+    def attempt_request(http_method, url, body, attempt)
+      perform(http_method, url, body)
+    rescue *TIMEOUT_ERRORS
+      raise Ipregistry::TimeoutError, "request timed out after #{@timeout}s" if attempt >= @max_retries
+
+      nil
+    rescue *CONNECTION_ERRORS => e
+      raise Ipregistry::ConnectionError, "request failed: #{e.message}" if attempt >= @max_retries
+
+      nil
+    end
+
+    def perform(http_method, url, body)
+      uri = URI.parse(url)
+      request = build_request(http_method, uri, body)
+
+      Net::HTTP.start(uri.host, uri.port,
+                      use_ssl: uri.scheme == "https",
+                      open_timeout: @timeout,
+                      read_timeout: @timeout,
+                      write_timeout: @timeout) do |http|
+        http.request(request)
+      end
+    end
+
+    def build_request(http_method, uri, body)
+      request = case http_method
+                when :get then Net::HTTP::Get.new(uri)
+                when :post then Net::HTTP::Post.new(uri)
+                else raise ArgumentError, "unsupported HTTP method: #{http_method}"
+                end
+      request["Authorization"] = "ApiKey #{@api_key}"
+      request["User-Agent"] = @user_agent
+      request["Accept"] = "application/json"
+      if body
+        request["Content-Type"] = "application/json"
+        request.body = body
+      end
+      request
+    end
+
+    def parse_json(body)
+      JSON.parse(body)
+    rescue JSON::ParserError
+      raise ParseError, "failed to decode response body as JSON"
+    end
+
+    # Converts a non-2xx response into the most specific ApiError, falling
+    # back to a generic message when the body is not a recognizable error
+    # payload.
+    def api_error(response, status)
+      payload = begin
+        JSON.parse(response.body.to_s)
+      rescue JSON::ParserError
+        nil
+      end
+
+      if payload.is_a?(Hash) && payload["code"]
+        ApiError.from_payload(payload, http_status: status)
+      else
+        ApiError.new("unexpected HTTP status #{status}", http_status: status)
+      end
+    end
+
+    def retry_status?(status)
+      return @retry_on_too_many_requests if status == 429
+
+      status.between?(500, 599) && @retry_on_server_error
+    end
+
+    # Delay before the next retry attempt, honoring an explicit Retry-After
+    # duration when positive and otherwise using exponential backoff.
+    def backoff_delay(attempt, retry_after)
+      return retry_after if retry_after&.positive?
+
+      @retry_interval * (2**[attempt, 30].min)
+    end
+
+    # Parses a Retry-After header expressed as an integer number of seconds.
+    # Returns nil when the header is absent or not a valid non-negative
+    # integer (the HTTP-date form is not supported).
+    def retry_after(response)
+      value = response["Retry-After"]
+      return nil unless value&.match?(/\A\d+\z/)
+
+      Integer(value, 10)
+    end
+
+    def wait(seconds)
+      sleep(seconds) if seconds.positive?
+    end
+  end
+end

data/lib/ipregistry/errors.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Ipregistry
+  # Base class for every error raised by this library. Rescue it to handle any
+  # Ipregistry failure with a single clause:
+  #
+  #   begin
+  #     client.lookup("8.8.8.8")
+  #   rescue Ipregistry::Error => e
+  #     # ...
+  #   end
+  class Error < StandardError; end
+
+  # Raised for failures that occur on the client side rather than being
+  # reported by the API, such as network errors or a response that cannot be
+  # decoded. The underlying cause, when any, is available through #cause.
+  class ClientError < Error; end
+
+  # Raised when a connection to the API cannot be established or is
+  # interrupted (DNS failure, connection refused, TLS error, ...).
+  class ConnectionError < ClientError; end
+
+  # Raised when a request does not complete within the configured timeout.
+  class TimeoutError < ClientError; end
+
+  # Raised when a response body cannot be decoded as JSON.
+  class ParseError < ClientError; end
+
+  # Raised when the Ipregistry API reports a failure, such as an invalid IP
+  # address, an exhausted credit balance, or throttling.
+  #
+  # Each documented error code maps to a dedicated subclass (for example
+  # +INVALID_API_KEY+ raises {InvalidApiKeyError}), so callers can rescue the
+  # exact condition they care about. The raw code, the suggested resolution,
+  # and the HTTP status remain available on every instance.
+  #
+  # In batch lookups, an ApiError may also describe the failure of a single
+  # entry rather than the whole request (see {BatchResponse}); such per-entry
+  # errors are returned, not raised.
+  #
+  # The full list of error codes is documented at
+  # https://ipregistry.co/docs/errors
+  class ApiError < Error
+    # @return [String, nil] the raw error code returned by the API
+    attr_reader :code
+
+    # @return [String, nil] a suggestion on how to resolve the error
+    attr_reader :resolution
+
+    # @return [Integer, nil] the HTTP status of the response, when known
+    attr_reader :http_status
+
+    def initialize(message = "API error", code: nil, resolution: nil, http_status: nil)
+      @code = code
+      @resolution = resolution
+      @http_status = http_status
+      super(message)
+    end
+
+    # Builds the most specific error for a decoded API error payload.
+    #
+    # @param payload [Hash] the decoded error body ("code", "message", "resolution")
+    # @param http_status [Integer, nil] the HTTP status of the response
+    # @return [ApiError] an instance of the subclass matching the error code,
+    #   or of ApiError itself when the code is not recognized
+    def self.from_payload(payload, http_status: nil)
+      payload = {} unless payload.is_a?(Hash)
+      code = payload["code"]
+      klass = ERRORS_BY_CODE.fetch(code, ApiError)
+      klass.new(
+        payload["message"] || "API error",
+        code: code,
+        resolution: payload["resolution"],
+        http_status: http_status
+      )
+    end
+  end
+
+  class BadRequestError < ApiError; end
+  class DisabledApiKeyError < ApiError; end
+  class ForbiddenIpError < ApiError; end
+  class ForbiddenOriginError < ApiError; end
+  class ForbiddenIpOriginError < ApiError; end
+  class InternalError < ApiError; end
+  class InsufficientCreditsError < ApiError; end
+  class InvalidApiKeyError < ApiError; end
+  class InvalidAsnError < ApiError; end
+  class InvalidFilterSyntaxError < ApiError; end
+  class InvalidIpAddressError < ApiError; end
+  class MissingApiKeyError < ApiError; end
+  class ReservedAsnError < ApiError; end
+  class ReservedIpAddressError < ApiError; end
+  class TooManyAsnsError < ApiError; end
+  class TooManyIpsError < ApiError; end
+  class TooManyRequestsError < ApiError; end
+  class TooManyUserAgentsError < ApiError; end
+  class UnknownAsnError < ApiError; end
+
+  # Maps raw Ipregistry API error codes to their dedicated error class. See
+  # https://ipregistry.co/docs/errors for the authoritative list.
+  ERRORS_BY_CODE = {
+    "BAD_REQUEST" => BadRequestError,
+    "DISABLED_API_KEY" => DisabledApiKeyError,
+    "FORBIDDEN_IP" => ForbiddenIpError,
+    "FORBIDDEN_ORIGIN" => ForbiddenOriginError,
+    "FORBIDDEN_IP_ORIGIN" => ForbiddenIpOriginError,
+    "INTERNAL" => InternalError,
+    "INSUFFICIENT_CREDITS" => InsufficientCreditsError,
+    "INVALID_API_KEY" => InvalidApiKeyError,
+    "INVALID_ASN" => InvalidAsnError,
+    "INVALID_FILTER_SYNTAX" => InvalidFilterSyntaxError,
+    "INVALID_IP_ADDRESS" => InvalidIpAddressError,
+    "MISSING_API_KEY" => MissingApiKeyError,
+    "RESERVED_ASN" => ReservedAsnError,
+    "RESERVED_IP_ADDRESS" => ReservedIpAddressError,
+    "TOO_MANY_ASNS" => TooManyAsnsError,
+    "TOO_MANY_IPS" => TooManyIpsError,
+    "TOO_MANY_REQUESTS" => TooManyRequestsError,
+    "TOO_MANY_USER_AGENTS" => TooManyUserAgentsError,
+    "UNKNOWN_ASN" => UnknownAsnError
+  }.freeze
+end