Quick Start

Get your first rate limit check working in two steps.

1. Create a bucket

A bucket defines your rate limit policy. Use your ADMIN_TOKEN to create one. You only need to do this once.

curl -X POST https://api.waitstate.io/v1/buckets \
  -H "Authorization: Bearer $WAITSTATE_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-api","capacity":100,"refill_rate":1}'

Response:

{
  "id": "01J8KM2P4XQYZ",
  "name": "my-api",
  "capacity": 100,
  "refill_rate": 1,
  "region": null,
  "log_webhook": null,
  "log_sampling": 1,
  "created_at": 1739832000,
  "updated_at": 1739832000
}

2. Check a limit

Call POST /v1/deduct before each operation you want to rate limit. Use your DEDUCT_TOKEN.

curl -X POST https://api.waitstate.io/v1/deduct \
  -H "Authorization: Bearer $WAITSTATE_DEDUCT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key":"user_123","bucket":"my-api","cost":1}'

Allowed (200):

HTTP/1.1 200 OK
X-WaitState-Limit: 100
X-WaitState-Remaining: 99
X-WaitState-Reset: 1739832160

{"allowed":true}

Denied (429):

HTTP/1.1 429 Too Many Requests
Retry-After: 5

{"error":"wait_state_active","message":"Quota exhausted. Required 1 units.","retry_after":5}

Core Concepts

Buckets

A bucket defines your rate limit policy for a given operation. It has two parameters:

• capacity: the maximum number of tokens a user can accumulate (controls burst size)
• refill_rate: tokens added per second (controls sustained throughput)

Example: capacity: 100, refill_rate: 1 allows a burst of up to 100 requests, then sustains 1 request per second. Each user gets their own isolated token bucket; the policy applies per user, not globally.

Create buckets once with your admin token. You can update capacity, refill_rate, and logging config at any time. The region field is set at creation and cannot be changed.

Keys

The key field identifies the entity being rate limited, typically a user ID or API key. WaitState creates an isolated token bucket for every unique key + bucket pair. There is no limit to the number of keys per bucket.

Hash before sending:

echo -n "user@example.com" | sha256sum | awk '{print $1}'
# a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3

import { createHash } from 'node:crypto'
const key = createHash('sha256').update(userId).digest('hex')

import hashlib
key = hashlib.sha256(user_id.encode()).hexdigest()

import (
    "crypto/sha256"
    "encoding/hex"
)

h := sha256.Sum256([]byte(userID))
key := hex.EncodeToString(h[:])

require 'digest'
key = Digest::SHA256.hexdigest(user_id)

Cost

The cost field is the number of tokens to deduct for this request. You calculate it client-side; WaitState never sees your request payload or protocol. This makes it work equally well with REST, GraphQL, gRPC, WebSockets, or any other protocol.

If cost is omitted it defaults to 1. Cost must be a positive number.

Common rate limit patterns

Set capacity and refill_rate on the bucket, then pass cost: 1 per request. The math: refill_rate is tokens per second, so multiply by 60 to get tokens per minute.

Authentication

WaitState uses two separate bearer tokens. They are scoped to different operations intentionally. If your production environment is compromised, your bucket configuration remains safe.

Pass either token as a standard HTTP bearer:

Authorization: Bearer <your-token>

All requests without a valid token return 401 Unauthorized. Tokens sent to the wrong endpoint also return 401. The DEDUCT_TOKEN cannot access bucket CRUD and vice versa.

Integration Examples

These examples show how to call /v1/deduct from common server-side runtimes. The pattern is always the same: hash the user ID, POST to WaitState, branch on the status code.

# Hash your user ID before sending -- never send raw PII
KEY=$(echo -n "user_123" | sha256sum | awk '{print $1}')

curl -X POST https://api.waitstate.io/v1/deduct \
  -H "Authorization: Bearer $WAITSTATE_DEDUCT_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"key\":\"$KEY\",\"bucket\":\"my-api\",\"cost\":1}"

# 200 OK  ->  {"allowed":true}
# 429     ->  {"error":"wait_state_active","retry_after":5}

import { createHash } from 'node:crypto'

const TOKEN = process.env.WAITSTATE_DEDUCT_TOKEN!

function sha256(s: string) {
  return createHash('sha256').update(s).digest('hex')
}

export async function allow(userId: string, cost = 1): Promise<boolean> {
  const res = await fetch('https://api.waitstate.io/v1/deduct', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ key: sha256(userId), bucket: 'my-api', cost }),
  })

  if (res.ok) return true

  if (res.status === 429) {
    const { retry_after } = await res.json() as { retry_after: number }
    // forward to caller: reply.header('Retry-After', String(retry_after))
    return false
  }

  throw new Error(`WaitState error: ${res.status}`)
}

import hashlib, os
import httpx

TOKEN = os.environ['WAITSTATE_DEDUCT_TOKEN']

def sha256(s: str) -> str:
    return hashlib.sha256(s.encode()).hexdigest()

def allow(user_id: str, cost: int = 1) -> bool:
    r = httpx.post(
        'https://api.waitstate.io/v1/deduct',
        headers={'Authorization': f'Bearer {TOKEN}'},
        json={'key': sha256(user_id), 'bucket': 'my-api', 'cost': cost},
    )
    if r.status_code == 200:
        return True
    if r.status_code == 429:
        retry_after = r.json()['retry_after']
        # raise RateLimitError(retry_after=retry_after)
        return False
    r.raise_for_status()

package ratelimit

import (
	"bytes"
	"crypto/sha256"
	"encoding/hex"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

var token = os.Getenv("WAITSTATE_DEDUCT_TOKEN")

type Result struct {
	Allowed    bool
	RetryAfter int
}

func Allow(userID string, cost int) (Result, error) {
	h := sha256.Sum256([]byte(userID))
	body, _ := json.Marshal(map[string]any{
		"key":    hex.EncodeToString(h[:]),
		"bucket": "my-api",
		"cost":   cost,
	})

	req, _ := http.NewRequest(http.MethodPost,
		"https://api.waitstate.io/v1/deduct",
		bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer "+token)
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		return Result{}, err
	}
	defer resp.Body.Close()

	switch resp.StatusCode {
	case 200:
		return Result{Allowed: true}, nil
	case 429:
		var r struct {
			RetryAfter int `json:"retry_after"`
		}
		json.NewDecoder(resp.Body).Decode(&r)
		return Result{Allowed: false, RetryAfter: r.RetryAfter}, nil
	default:
		return Result{}, fmt.Errorf("waitstate: status %d", resp.StatusCode)
	}
}

require 'digest'
require 'json'
require 'net/http'

TOKEN = ENV.fetch('WAITSTATE_DEDUCT_TOKEN')

def allow(user_id, cost: 1)
  key = Digest::SHA256.hexdigest(user_id)
  uri = URI('https://api.waitstate.io/v1/deduct')

  Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
    req = Net::HTTP::Post.new(uri,
      'Authorization' => "Bearer #{TOKEN}",
      'Content-Type'  => 'application/json')
    req.body = { key:, bucket: 'my-api', cost: }.to_json

    res = http.request(req)
    return true  if res.code == '200'
    return false if res.code == '429'
    raise "WaitState error: #{res.code}"
  end
end

The bucket field accepts either the bucket id or name. Using the name is more readable; using the ID is slightly faster and avoids breaking if you rename a bucket.

Client Libraries

Official client libraries are in development. They will handle SHA-256 hashing, response header parsing, retry logic, and error propagation automatically. All libraries will be MIT-licensed and open source.

Deduct Tokens

Atomically deducts tokens from a user's bucket and returns whether the request is allowed.

Request body

200 OK

{ "allowed": true }

Response headers are always set. See Response Headers.

429 Too Many Requests

{
  "error": "wait_state_active",
  "message": "Quota exhausted. Required 10 units.",
  "retry_after": 5
}

retry_after is the number of seconds until enough tokens have refilled to allow the same cost. Forward this value to your client as a Retry-After header.

Response Headers

Every response includes these headers, regardless of whether the request was allowed or denied.

List Buckets

Returns all buckets, newest first.

[
  {
    "id": "01J8KM2P4XQYZ",
    "name": "graphql-api",
    "capacity": 1000,
    "refill_rate": 10,
    "region": "wnam",
    "log_webhook": null,
    "log_sampling": 1.0,
    "created_at": 1739832000,
    "updated_at": 1739832000
  },
  {
    "id": "01J8KM2P4ABCD",
    "name": "rest-api",
    "capacity": 100,
    "refill_rate": 1,
    "region": null,
    "log_webhook": "https://ingest.example.com/waitstate",
    "log_sampling": 0.1,
    "created_at": 1739831000,
    "updated_at": 1739831000
  }
]

Create Bucket

Creates a new bucket. Returns 201 Created with the full bucket object.

Request body

Bucket object

{
  "id": "01J8KM2P4XQYZ",
  "name": "my-api",
  "capacity": 100,
  "refill_rate": 1,
  "region": "wnam",
  "log_webhook": null,
  "log_sampling": 1.0,
  "created_at": 1739832000,
  "updated_at": 1739832000
}

Get Bucket

Returns a single bucket by ID. Returns 404 if not found.

Update Bucket

Partial update. All fields are optional. region is immutable and cannot be changed after creation. Returns the updated bucket object.

Delete Bucket

Deletes the bucket definition. Returns 204 No Content. This does not immediately destroy existing Durable Object state for active users; those will expire naturally.

Regions

By default, WaitState uses Smart Placement to automatically co-locate each rate limiter near your application servers. If your users are concentrated in a specific geography, you can pin a bucket to a region for more predictable latency.

Set region when creating a bucket. It cannot be changed after creation.

Log Delivery

WaitState can emit a structured log record for every rate limit check. Logs are useful for auditing, debugging, and building dashboards. Configure logging per bucket.

Webhook delivery

Set log_webhook to an HTTPS URL and WaitState will POST each log record there as JSON. Use this to ship logs to Datadog, Splunk, a custom ingest endpoint, or anywhere that accepts HTTP.

curl -X PUT https://api.waitstate.io/v1/buckets/<id> \
  -H "Authorization: Bearer $WAITSTATE_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"log_webhook":"https://ingest.example.com/waitstate","log_sampling":0.1}'

The request is fire-and-forget. WaitState does not retry failed webhook calls. If your endpoint is unavailable, those log records are dropped. If no webhook is set, logs are written to internal R2 storage.

Log record format

{
  "ts": 1739832100,
  "bucket_id": "01J8KM2P4XQYZ",
  "key_hash": "a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3",
  "cost": 10,
  "allowed": false,
  "remaining": 0,
  "retry_after": 5
}

Sampling

For high-volume buckets, reduce log volume with log_sampling. Set it to a value between 0.0 and 1.0 representing the fraction of events to log.

Sampling is applied randomly and independently per request. It is not guaranteed to produce an exact percentage, but converges at volume.

Error Reference