Developers

Errors and limits

Every error has the same shape. Rate limits are sent in headers on every response.

Error shape

Error

{
  "error": {
    "code": "not_found",
    "message": "No Roblox game with place or universe id 1 on CCUCheck. Try /api/v1/search?q=<name>.",
    "status": 404,
    "docs": "https://ccucheck.com/docs/errors-and-limits"
  }
}

Codes

Status	code	When
400	`bad_request`	A parameter is missing or out of range. The message says which.
400	`key_in_url`	A key was sent in the URL. Use the Authorization header.
401	`invalid_key`	The key is wrong or revoked. Requests with a bad key are refused, not treated as unsigned.
403	`forbidden`	Not on your plan, for example more history than it covers (`max_days` says how much).
404	`not_found`	No such game on CCUCheck.
404	`not_available`	CCUCheck found the game in the last 14 days, which needs Studio.
429	`rate_limited`	Too many requests. See below.
503	`unavailable`	A part of the service is briefly unavailable. Retry after a few seconds.
500	`internal`	Something went wrong on our side.

Rate limits

Who	Requests	Per minute	History	Keys
No key	60 a hour	20	30 days	None
Free key	1,000 a day	60	30 days	3
Pro key	20,000 a day	300	Everything	10

Every response carries the current window:

Headers

RateLimit-Limit: 1000
RateLimit-Remaining: 987
RateLimit-Reset: 51840
RateLimit-Policy: 1000;w=86400

RateLimit-Reset is seconds until the window resets. There is also a short per-minute ceiling (the "Per minute" column), so a script cannot spend a whole day in seconds. Unsigned calls are counted per IP address; key calls per account.

When you hit a limit

429 Too Many Requests

{
  "error": {
    "code": "rate_limited",
    "message": "You have used this hour's 60 requests. Retry in 1520 seconds, or use an API key for a bigger allowance.",
    "status": 429,
    "docs": "https://ccucheck.com/docs/errors-and-limits",
    "limit": 60,
    "window": "hour",
    "scope": "plan",
    "retry_after": 1520,
    "reset_at": "2026-10-27T10:00:00.000Z"
  }
}

scope is plan for your allowance, burst for the per-minute ceiling, or global when unsigned traffic as a whole is busy. Wait retry_after seconds (also in the Retry-After header) before retrying, and back off further if it repeats.

{ "error": { "code": "not_found", "message": "No Roblox game with place or universe id 1 on CCUCheck. Try /api/v1/search?q=<name>.", "status": 404, "docs": "https://ccucheck.com/docs/errors-and-limits" } }