package polymarket

  1. Overview
  2. Docs

Module Polymarket_rate_limiter.Rate_limiterSource

Route-based rate limiting for HTTP clients.

This library provides GCRA-based rate limiting with route matching, supporting multiple limits per route and configurable delay/error behaviors.

Quick Start

  (* Create a shared rate limiter with Polymarket API limits *)
  let routes = Polymarket_common.Rate_limit_presets.all ~behavior:Delay in
  let rate_limiter =
    Rate_limiter.create ~routes ~clock:(Eio.Stdenv.clock env) ()
  in

  (* Pass to all API clients *)
  let gamma = Gamma.create ~sw ~net ~rate_limiter () in
  let data = Data.create ~sw ~net ~rate_limiter () in

Features

  • Route matching: Match requests by host, HTTP method, and path prefix
  • Multiple limits: Stack burst and sustained limits on the same route
  • GCRA algorithm: Fair rate limiting using Generic Cell Rate Algorithm
  • Configurable behavior: Delay requests or return errors per route

Core Types

Sourcetype behavior = Types.behavior =
  1. | Delay
  2. | Error
    (*

    Behavior when rate limit is exceeded

    *)
Sourcetype route_pattern = Types.route_pattern = {
  1. host : string option;
  2. method_ : string option;
  3. path_prefix : string option;
}

Route matching pattern

Sourcetype limit_config = Types.limit_config = {
  1. requests : int;
  2. window_seconds : float;
}

Rate limit configuration

Sourcetype route_config = Types.route_config = {
  1. pattern : route_pattern;
  2. limits : limit_config list;
  3. behavior : behavior;
}

Complete route configuration

Sourcetype error = Types.error =
  1. | Rate_limited of {
    1. retry_after : float;
    2. route_key : string;
    }
    (*

    Rate limiter error

    *)

Rate Limiter

Sourcetype t

Rate limiter state

Sourceexception Rate_limit_exceeded of error

Raised by before_request when behavior is Error and limit exceeded

Sourceval create : routes:route_config list -> clock:_ Eio.Time.clock -> ?max_idle_time:float -> unit -> t

Create a rate limiter with custom routes.

  • parameter routes

    Rate limit configurations (all matching routes apply)

  • parameter clock

    Eio clock for timing and delays

  • parameter max_idle_time

    For cleanup: remove states unused for this long (default: 300.0)

Sourceval update_routes : t -> route_config list -> unit

Update the rate limit routes at runtime

Sourceval before_request : t -> method_:string -> uri:Uri.t -> unit

Check rate limits before making a request.

  • For Delay behavior: sleeps until the request is allowed
  • For Error behavior: raises Rate_limit_exceeded if limit exceeded
Sourceval before_request_result : t -> method_:string -> uri:Uri.t -> (unit, error) result

Like before_request but returns a result instead of raising.

State Management

Sourceval cleanup : t -> unit

Remove stale state entries (unused longer than max_idle_time)

Sourceval state_count : t -> int

Get the number of active state entries

Sourceval reset : t -> unit

Clear all rate limit state (for testing)

Sub-modules

Sourcemodule Types = Types
Sourcemodule Builder = Builder
Sourcemodule Gcra = Gcra
Sourcemodule State = State
Sourcemodule Matcher = Matcher