Skip to content

rate-limits.mdx

Latest commit

 

History

History
251 lines (207 loc) · 5.89 KB

rate-limits.mdx

File metadata and controls

251 lines (207 loc) · 5.89 KB
title API Rate Limits
description Understanding Spoo.me API rate limits and best practices
icon clock

Spoo.me API implements rate limiting to ensure fair usage and maintain service quality for all users. Rate limits vary based on authentication method and API version.

API v1 Rate Limits (Recommended)

The new v1 API offers significantly higher rate limits with authentication:

With Authentication (JWT or API Key)

**60 requests** **5,000 requests** All v1 endpoints

Without Authentication (Anonymous)

**20 requests** **1,000 requests** Limited endpoints **Get 3x more requests** by using [API keys](/api-keys) or JWT authentication! Anonymous users are limited to 20 requests/minute vs 60 requests/minute for authenticated users.

API v0 Rate Limits (Legacy)

The legacy v0 API has lower rate limits:

**10 short URLs** per IP **100 short URLs** per IP **500 short URLs** per IP The v0 API is **legacy** and does not support authentication. We recommend migrating to the v1 API for better rate limits and features.

Rate Limits by Endpoint

URL Shortening

v1 API Endpoints

Endpoint Authenticated Anonymous Notes
POST /api/v1/shorten 60/min, 5000/day 20/min, 1000/day v1 API

v0 API Endpoints (Legacy)

The following endpoints are part of the legacy v0 API. They do not support authentication and have lower rate limits.
Endpoint Authenticated Anonymous Notes
POST / - 10/min, 100/hr, 500/day v0 API (legacy)
POST /emoji - 10/min, 100/hr, 500/day v0 API (legacy)

URL Management

Endpoint Authenticated Anonymous Notes
GET /api/v1/urls 60/min, 5000/day Not allowed Requires auth
PATCH /api/v1/urls/{id} 60/min, 5000/day Not allowed Requires auth
PATCH /api/v1/urls/{id}/status 60/min, 5000/day Not allowed Requires auth
DELETE /api/v1/urls/{id} 60/min, 5000/day Not allowed Requires auth

Analytics

Endpoint Authenticated Anonymous Notes
GET /api/v1/stats 60/min, 5000/day 20/min, 1000/day Public URLs only for anon
POST /stats/{code} - - v0 API (legacy)
POST /export/{code}/{format} - - v0 API (legacy)

Authentication & Rate Limits

How you authenticate directly affects your rate limits:

**Rate Limits**: 60/min, 5000/day 
**Benefits**:
- 3x higher rate limits vs anonymous
- Access to URL management endpoints
- Private stats support
- Long-lived tokens for automation

**How to use**: [Create an API key](/api-keys) and include it in the `Authorization` header:
```bash
Authorization: Bearer spoo_YOUR_API_KEY
```
**Rate Limits**: 60/min, 5000/day 
**Benefits**:
- Same rate limits as API keys
- Full dashboard access
- Can create/manage API keys
- Manage URLs via web UI

**How to use**: Obtain JWT via OAuth/login and include in header:
```bash
Authorization: Bearer YOUR_JWT_TOKEN
```
**Rate Limits**: 20/min, 1000/day 
**Limitations**:
- 3x lower rate limits
- Cannot manage URLs later
- No access to private stats
- Cannot use URL management endpoints

**How to use**: Simply make requests without authentication header.

Rate Limit Headers

When you make requests to rate-limited endpoints, the response will include headers indicating your current usage:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1640995200
Retry-After: 30

Handling Rate Limits

When you exceed the rate limit, you'll receive a 429 Too Many Requests response:

{
  "error": "Rate limit exceeded"
}

Need Higher Limits?

If you need higher rate limits for your application:

If you still need higher limits, contact our support team at [support@spoo.me](mailto:support@spoo.me) with: - Details about your use case - Expected request volume - Description of your application

Next Steps

Get started with API key authentication Explore all available endpoints Build your first integration Use our official SDK