GETTING STARTED
Rate limits
One window: requests per API key per hour. Blow through it and you get a 429 until the hour resets.
CURRENT LIMITS
500 / hour
per API key
Free-tier default, set per key at creation — the dashboard and
X-RateLimit-Limitalways show your key's real number.RATE LIMIT HEADERS
Every response tells you where you stand:
X-RateLimit-Limit
number
Maximum requests allowed in the current window.
X-RateLimit-Remaining
number
Requests remaining in the current window.
X-RateLimit-Reset
ISO-8601 string
When the current window resets, e.g.
2026-01-15T01:00:00.000Z.HANDLING 429S
Watch X-RateLimit-Remaining and slow down before you hit zero. On a 429, wait retryAfterseconds (or use exponential backoff, right). Cache responses locally — ratings don't change often — and avoid bursts of parallel requests; batch where you can.
NEED HIGHER LIMITS? OPEN A GITHUB ISSUE (WKOVERFIELD/NBA2KAPI) WITH YOUR USE CASE.
RESPONSE HEADERS
X-RateLimit-Limit: 500 X-RateLimit-Remaining: 463 X-RateLimit-Reset: 2026-01-15T01:00:00.000Z
429 TOO MANY REQUESTS
{
"success": false,
"error": {
"message": "You have exceeded your rate limit.
Please try again in 45 seconds",
"code": "RATE_LIMIT_EXCEEDED",
"details": {
"limit": 500,
"reset": "2025-01-15T00:45:00.000Z",
"retryAfter": 45
},
"timestamp": "2025-01-15T00:00:00.000Z"
}
}RETRY WITH BACKOFF
async function fetchWithRetry(url, options, maxRetries = 3) {
for (let i = 0; i < maxRetries; i++) {
const response = await fetch(url, options);
if (response.status !== 429) {
return response;
}
// Exponential backoff: 1s, 2s, 4s
const delay = Math.pow(2, i) * 1000;
await new Promise(resolve => setTimeout(resolve, delay));
}
throw new Error('Max retries exceeded');
}