Rate Limits and Caching on banner.yt

Knowing how rate limits and caching work will help you build reliable apps with the banner.yt API.

Rate limits

The default rate limit is 10 requests per 30 seconds per IP address. This applies to all endpoints.

When you exceed the limit, the API returns HTTP 429 with a plain text response. The limit resets after 30 seconds.

Handling 429s in your code

async function fetchBanner(channelId, retries = 3) {
  const res = await fetch(`https://banner.yt/api/banner/${channelId}`);

  if (res.status === 429 && retries > 0) {
    await new Promise(r => setTimeout(r, 5000)); // wait 5s
    return fetchBanner(channelId, retries - 1);
  }

  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  return res;
}

Image caching

All image responses come back with:

Cache-Control: public, max-age=86400, s-maxage=86400, stale-while-revalidate=43200

This means:

Browsers and CDNs cache the image for 24 hours (86400 seconds)
After 24 hours, stale-while-revalidate lets the CDN serve the old image while fetching a fresh one in the background
On the server, images are cached in Redis for 24 hours

Channel data caching

The /api/channel endpoint caches results for 1 hour. Subscriber counts and view counts update roughly every hour.

Best practices for high traffic

Proxy images through your own CDN (Cloudflare, Vercel, etc.) so the banner.yt server only gets one request per image per day
Cache channel data in your own database rather than hitting the API on every page load
For batch operations, spread requests out over time instead of firing them all at once
Use the search endpoint to find channel IDs once, then store them and use the channel ID directly afterward

Cache busting

If a channel has updated their banner and you want to force a fresh fetch, append a timestamp or add ?nocache=1 to the URL. Note this bypasses the server cache and will count against your rate limit.