Rate Limits

The Bitrefill API uses rate limiting to ensure fair usage and system stability. This page documents the limits and how to work within them.

Rate Limit Overview

Rate limits are applied per endpoint and measured over a rolling time window. When you exceed a limit, you'll receive a 429 Too Many Requests response.

Endpoint Limits

Endpoint	Limit	Window
`GET /ping`	1 request	3 seconds
`GET /check_phone_number`	10 requests	1 minute
`GET /accounts/balance`	60 requests	10 minutes
`GET /products`	60 requests	1 minute
`GET /products/{id}`	60 requests	1 minute
`GET /products/esims`	60 requests	1 minute
`GET /products/esims/{id}`	60 requests	1 minute
`GET /products/search`	60 requests	1 minute
`GET /invoices`	20 requests	1 minute
`GET /invoices/{id}`	60 requests	10 minutes
`POST /invoices`	60 requests	10 minutes
`POST /invoices/{id}/pay`	60 requests	10 minutes
`GET /esims/invoice/{id}`	60 requests	10 minutes
`POST /esims`	60 requests	10 minutes
`POST /esims/invoice/{id}/pay`	60 requests	10 minutes
`GET /orders`	20 requests	1 minute
`GET /orders/{id}`	60 requests	10 minutes
`GET /esims`	20 requests	1 minute
`GET /esims/{id}`	60 requests	10 minutes

Product Quota Limiter

In addition to per-endpoint rate limits, there's a quota limiter for product-related requests:

Limit: 1000 requests per hour
Applies to: /products and /products/search endpoints

This quota is separate from the per-endpoint rate limits.

Rate Limit Headers

Every response includes rate limit information:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1704067200

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

Use Webhooks Instead of Polling

Instead of repeatedly checking invoice status, use webhooks:

// Good: Use webhooks
const invoice = await createInvoice({
  products: [...],
  webhook_url: 'https://your-server.com/webhook'
});