Building Rate-Limited Public APIs That Partners Can Actually Build On

The single biggest source of partner frustration on a public API we built for a client wasn't bugs, it was unpredictability — rate limits that weren't documented anywhere, so partners discovered their actual ceiling by hitting 429s in production. We fixed this by publishing exact limits per plan tier (requests per minute and per day) directly in the API docs and returning X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers on every response so partner code could self-throttle before hitting the wall.

We tiered limits by authenticated API key rather than IP address, since partners often called our API from shared infrastructure or serverless functions where IP-based limiting would have punished well-behaved partners for sharing infrastructure with noisy ones. Each key's limit was configurable per partner contract, which let us offer a generous default tier for free evaluation and a genuinely higher ceiling for paying partners without needing separate API infrastructure for each tier.

Error responses got the same predictability treatment as rate limits. Early on, our error responses were inconsistent — sometimes a string, sometimes an object, with HTTP status codes that didn't reliably map to error categories. We standardized on a consistent error envelope with a machine-readable error code, a human-readable message, and — where applicable — a field pointing to exactly which part of the request was invalid, which measurably cut the volume of partner support tickets asking 'what does this error mean.'

We built a sandbox environment with synthetic data and no rate limits specifically for partner integration testing, separate from production. Before that existed, partners were building and debugging their integrations directly against production limits, which meant a partner iterating on their implementation could burn through their daily quota just testing, then file a support ticket about hitting limits they hadn't even reached with real usage yet.

The last piece was giving partners visibility into their own usage without needing to ask us — a self-serve dashboard showing request volume, error rates, and current rate limit consumption over time. Partners who could see they were approaching a limit reached out proactively to discuss upgrading, rather than us finding out only after their integration started failing in front of their own customers, which was a meaningfully better conversation to have on both sides.