Rate Limits

The Upstat API implements rate limiting to ensure fair usage and maintain service quality. Understanding rate limits helps you build reliable integrations.

Rate Limit Overview

Rate limits are applied at two levels:

Per API Token:

Window	Limit
1 minute	1,000 requests
1 hour	10,000 requests

Per Account:

Window	Limit
1 minute	5,000 requests

When you exceed a rate limit, the API returns a 429 Too Many Requests status.

Rate Limit Headers

Every API response includes rate limit information:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1640995200

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed in the current window
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp when the window resets

When rate limited (429 status):

Retry-After: 30
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1640995200

Header	Description
`Retry-After`	Seconds to wait before retrying

Handling Rate Limits

Response Format

When rate limited, you receive:

Retry Strategy

Always respect the Retry-After header:

Proactive Rate Limit Checking

Check remaining requests before making calls:

Best Practices

Optimize Request Volume

Practice	Description
Use pagination efficiently	Request the maximum `limit` (100) when fetching lists
Cache responses	Store and reuse data that doesn’t change frequently
Use webhooks	Subscribe to events instead of polling
Batch operations	Group related changes into fewer requests

Implement Exponential Backoff

For transient errors and rate limits, use exponential backoff:

Retry	Wait Time
1	1 second
2	2 seconds
3	4 seconds
4	8 seconds
5	16 seconds

Monitor Your Usage

Track rate limit headers to understand your usage patterns:

const remaining = response.headers.get("X-RateLimit-Remaining");
const limit = response.headers.get("X-RateLimit-Limit");
const usage = ((limit - remaining) / limit * 100).toFixed(1);

console.log(`Rate limit usage: ${usage}%`);

Use Separate Tokens

For different parts of your application:

Token	Purpose
Production Read	High-volume read operations
Production Write	Create/update operations
Background Jobs	Scheduled tasks and syncs
Development	Testing and debugging

This distributes load across multiple per-token limits.