EZConfig

Community-maintained rate limits and concurrency settings for popular APIs.

No more guessing at rate limits or risking API bans - use battle-tested defaults contributed by the community.

Installation

gleam add ezconfig@1

Usage

import ezconfig
import gleam/option

pub fn main() {
  // Get full config for an API
  case ezconfig.get_config("api.openai.com") {
    option.Some(config) -> {
      // config.rps = 60 requests per second
      // config.max_concurrent = 10 concurrent requests
      // config.notes = "Tier 1: 60 req/min = 1 req/sec, but bursts allowed"
    }
    option.None -> {
      // Use your own defaults
    }
  }

  // Or get specific values
  let rps = ezconfig.get_rps("api.stripe.com")           // Some(100)
  let concurrent = ezconfig.get_max_concurrent("slack.com")  // Some(1)

  // Check if a domain has configuration
  let has_config = ezconfig.has_config("api.github.com")  // True

  // List all configured domains
  let domains = ezconfig.list_domains()
  // ["api.openai.com", "api.stripe.com", "api.github.com", ...]
}

Integration Pattern

With EZThrottle

When integrating with EZThrottle:

1. Default Configuration: Use ezconfig for initial rate limits and concurrency
2. Runtime Override: Response headers always take precedence

// Example: Setting defaults from ezconfig
let domain = extract_domain(job.url)  // "api.openai.com"

// Use ezconfig defaults if available
let default_rps = case ezconfig.get_rps(domain) {
  option.Some(rps) -> rps
  option.None -> 2  // Fallback to conservative default
}

let default_concurrent = case ezconfig.get_max_concurrent(domain) {
  option.Some(max) -> max
  option.None -> 2  // Fallback to conservative default
}

// Apply to URL queue
let queue = URLQueue(
  rate_limit_ms: float.round(1000.0 /. int.to_float(default_rps)),
  max_concurrent: default_concurrent,
  ...
)

// Later: Headers override config
// X-EZTHROTTLE-RPS: 100  -> Updates rate_limit_ms
// X-EZTHROTTLE-MAX-CONCURRENT: 20  -> Updates max_concurrent

Convention

Priority (highest to lowest):

1. Response Headers - APIs can dynamically tune their own limits
   • X-EZTHROTTLE-RPS: 100
   • X-EZTHROTTLE-MAX-CONCURRENT: 20
2. EZConfig Defaults - Community-verified safe values
3. System Defaults - Conservative fallback (2 RPS, 2 concurrent)

This allows:

• Safe defaults out of the box (via ezconfig)
• Dynamic tuning by API providers (via headers)
• Community contributions for better defaults (via PRs)

Configured APIs

Currently includes rate limit configurations for:

• AI/LLM: OpenAI, Anthropic (Claude)
• Payments: Stripe
• Dev Tools: GitHub
• Social: Twitter, Facebook, Discord
• Communication: Slack, SendGrid, Twilio
• Business: HubSpot, Notion, Airtable, Shopify
• More: Google APIs

See the full list in src/ezconfig.gleam.

Contributing

Want to add or update an API configuration?

1. Fork this repo
2. Update the api_configs() dict in src/ezconfig.gleam
3. Submit a PR with your changes

Please include links to official rate limit documentation in your PR.

License

MIT

Built for EZThrottle - Distributed async job execution with built-in rate limiting.