Rate Limits & Quota

The API uses a simple daily quota system. Every cached request is free — quota only applies when you explicitly force a live scrape with ?refresh=true.

How Quota Works

Request type	Quota cost
Served from a fresh cache (no ?refresh)	Free
Cache expired or missing (no ?refresh)	Free — the API re-scrapes the RSI website on its own budget
?refresh=true	1 daily request (10 for GET /v2/ships, which scrapes the whole ship catalog)

A ?refresh=true request is charged once, even when it refreshes several resources (for example GET /v2/users/:handle, which returns the profile and the organization).

Your daily limit is 500 requests per day. The counter resets automatically every day (see Quota Reset Schedule).

Every response carries an X-Quota-Consumed header with the number of daily requests the call used (0 unless it was a billed ?refresh=true).

tip

Most requests are free.

The smart cache keeps data for hours to days depending on the endpoint and re-scrapes it automatically once it expires, so for most use cases you never need ?refresh=true at all. See Data Freshness & Caching for how the cache strategy works and Refresh Intervals for how long each endpoint stays fresh.

Checking Your Daily Limit

Call GET /v2/me at any time to see your API key, daily limit and remaining requests without visiting the dashboard:

GET /v2/me HTTP/1.1
Host: apiv2.starcitizen-api.com
x-api-key: YOUR_API_KEY

{

  "success": true,

  "message": "ok",

  "data": {

    "_id": "665f1c2e8b1e4a0012ab34cd",

    "provider": "Discord",

    "key": "YOUR_API_KEY",

    "dailyRequestLimit": 500,

    "dailyRequestsRemaining": 500,

    "createdAt": "2025-05-18T00:00:00.000Z",

    "updatedAt": "2025-05-18T00:00:00.000Z",

    "blocked": null

  }

}

dailyRequestLimit is your total per day; dailyRequestsRemaining is what is left until the next reset. Only ?refresh=true requests decrement it. blocked is null unless the account is blocked, in which case it holds the reason.

tip

Build quota awareness into your app by reading dailyRequestsRemaining at startup. Use ?refresh=true only when you genuinely need real-time data right now — for everything else, let the smart cache work.

Quota Reset Schedule

Your daily quota resets once a day (midnight, server time, by default). To get the exact next-reset timestamp programmatically, call GET /management/status (no API key required):

GET /management/status HTTP/1.1
Host: apiv2.starcitizen-api.com

{
  "success": true,
  "message": "ok",
  "data": {
    "quotaReset": {
      "lastAt": "2025-05-18T00:00:00.000Z",
      "nextAt": "2025-05-19T00:00:00.000Z"
    },
    "cacheRefresh": {
      "lastAt": null,
      "nextAt": null
    }
  }
}

cacheRefresh is currently always null: there is no scheduled background cache refresh (see Data Freshness & Caching).

When You Hit the Limit

If you receive HTTP 429 with "Daily request quota exhausted":

• Drop ?refresh=true from requests where real-time data is not strictly required — requests without it are still served and never cost quota.
• Wait for your quota to reset (nextAt in GET /management/status).
• If you consistently need a higher daily limit, reach out via Discord.

Per-Minute Rate Limits

Per-minute limits apply on top of the daily quota. All are Redis-backed, reset with each one-minute window, and return HTTP 429.

Limit	Applies to	Default	Message
Global request limit	Every request, cached or live — counted per API key, or per IP without a key	120 requests per minute	Too many requests. Try again in the next minute.
Per API key scrape limit	Every live scrape (?refresh=true, or a request that finds an expired cache)	60 live scrapes per minute	API request rate limit exceeded. Try again in the next minute.
Global scrape limit	Every live scrape, shared by all users	60 live scrapes per minute	Scraping rate limit exceeded. Try again in the next minute.

The global request limit is reported on every response:

Header	Meaning
X-RateLimit-Limit	Requests allowed per minute
X-RateLimit-Remaining	Requests left in the current minute
X-RateLimit-Reset	Seconds until the current minute window resets
Retry-After	Sent with a 429 from the global request limit — seconds to wait before retrying

When you get a 429, back off and retry after the current minute window resets.