Skip to main content

Troubleshooting

Before You Dig In​

A few things to check first — these cover the majority of issues:

  • Check the HTTP status code. Errors use real status codes (401, 404, 429…) with success: false and a matching code in the body. See Error Codes.
  • Do not switch logic on message. The message field is human-readable and may change — only use it for display, never for conditional logic.
  • Retry on 503 and 504. These are usually brief (a scrape timeout or a temporary outage) — wait a few seconds and try again.
  • Handle 404 gracefully. It is returned when RSI has no such resource, for example an unknown handle or organization SID.

How to Test Requests Without Writing Code​

Postman is the quickest way to explore and debug API requests:

  1. Create a new GET request.
  2. Enter the endpoint URL, e.g. https://apiv2.starcitizen-api.com/v2/users/dymerz.
  3. In the Headers tab, add x-api-key with your API key as the value.
  4. Click Send.

You get the full request and response — status codes, headers, and body — without writing any code.

CORS Errors in the Browser​

The API answers cross-origin GET and OPTIONS requests from any origin and accepts the x-api-key header. Other methods (such as DELETE /v2/me) are not allowed cross-origin. If you still see a CORS error, check that:

  • you are sending a GET request to a /v2/... route, and no custom headers other than Content-Type and x-api-key;
  • the request reaches the API at all — a network or proxy error is often reported by the browser as a CORS error. Try the same request in Postman.

Even though the browser is allowed to call the API, don't.

warning

Keep your key off the client.

The key must be sent in a header, so calling the API from browser JavaScript exposes it to every visitor. Proxy API calls through your own backend and forward the response to your frontend.

API Key Not Working​

  • Confirm the key is passed in the x-api-key header, not as a query parameter or in the URL path.
  • Check for extra spaces or newline characters copied with the key.
  • Log in via the site to verify your key is still active on your profile page.
  • If you recently regenerated your key, make sure you are using the new one — the old key is immediately invalidated.

Data Seems Stale​

The API serves data from its internal cache by default. Each endpoint has a maximum data age (see Refresh Intervals); the first request after it expires triggers a re-scrape. Check updatedAt and expiresAt in the response to see how old the data is, and the X-Data-Source header to see whether it came from cache or live.

If the response looks genuinely outdated, add ?refresh=true to your request to force an immediate live scrape from the RSI website. Be aware this costs 1 daily request from your quota (10 for GET /v2/ships).

If a scrape fails or is slow, the API may serve the previous cached copy rather than an error, so updatedAt can be older than the interval suggests.

For the full explanation of how the cache strategy works and when data is refreshed, see Data Freshness & Caching.

Quota Exceeded​

HTTP 429 has two families of causes. If the message is Too many requests…, API request rate limit exceeded… or Scraping rate limit exceeded…, you hit a per-minute limit: wait for the minute window to reset (the Retry-After header tells you how long) and slow down.

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

  • Stop using ?refresh=true for requests where real-time data is not strictly required — requests without it are still served and never consume quota.
  • Your daily quota resets at a fixed time each day. Check Rate Limits & Quota for the exact next-reset time.
  • Log in and click Profile to check your remaining quota balance.
  • If you consistently need a higher quota, reach out via Discord.