Validation & status

Validate a key — isValid

RPDB-compatible endpoint that reports whether a key is valid plus its usage.

GET https://api.aioratings.com/{key}/isValid

Response (200):

{
  "validity": true,
  "limit": 0,
  "requestCount": 1234
}

Field	Meaning
validity	true for a valid key. An invalid key returns { "validity": false } (not a 401).
limit	The tier’s monthly request quota. 0 means unlimited (premium/pro).
requestCount	The live current-month request count for the key’s account.

Response headers (image endpoints)

Header	Meaning
X-Cache-Status	HIT (served from cache), MISS-FALLBACK (plain poster while rendering), etc.
X-Elements-Hash	Identifies the exact design that produced the image; the cache is keyed on it.

See How posters render for the full cache/fallback lifecycle.

Error responses

Status	When
200	Image (or isValid JSON) returned successfully.
400	Invalid id type — must be imdb, tmdb or tvdb.
403	A free key requested a non-default custom profile (premium/pro only).
422	Invalid poster profile.
500	Internal server error.

In practice you rarely see a hard 404 for a real title: aioratings always falls back to the plain source poster on a cache miss, so a valid id returns an image even before its rated render exists.

Usage metering

Every ratings/poster request is logged, and a daily roll-up aggregates per-user monthly usage. The advertised per-tier call allowances are tracked; treat them as the published limits and check Plans & limits for the current numbers.