Error handling

These error conventions apply to the Toplist API. Stats postbacks and the Ad Server API report errors in their own formats, described on their own pages.

Always send Accept: application/json on every request, including auth exchanges. Requests run on a middleware stack that needs this header to return the JSON error shapes below. Without it, a validation or throttling error can come back as an HTML redirect instead.

Status	error	When	Body example
401	invalid_credentials	Token exchange: key not found, or secret is wrong (identical response for both, deliberately, so a caller can't use the response to figure out whether a key exists at all)	{"error":"invalid_credentials","message":"Invalid API key or secret."}
403	ip_not_allowed	Token exchange: caller's IP isn't on that credential's allowlist	{"error":"ip_not_allowed","message":"Your IP address is not in the allowed list for this credential."}
401	unauthenticated	Any data endpoint: missing/invalid/expired bearer token, or an IP-allowlist mismatch on this path (surfaces identically to a bad token, not as a 403)	{"error":"unauthenticated","message":"Invalid or missing API token."}
403	insufficient_scope	Any data endpoint: your credential doesn't carry the scope that endpoint requires	{"error":"insufficient_scope","message":"This credential does not have the required scope: toplist:read"}
404	not_found	Single-resource lookups: no matching, currently-available resource	{"error":"not_found","message":"Toplist not found or not available."}
422	N/A (standard validation)	Token exchange: a required field is missing from the request body	{"message":"The key field is required. (and 1 more error)","errors":{"key":["The key field is required."],"secret":["The secret field is required."]}}
429	N/A (standard throttle)	Rate limit exceeded	Standard Retry-After / X-RateLimit-* headers, {"message":"Too Many Attempts."}

Rate limits are set per endpoint and per credential. Check the specific API's reference pages (for example, the Toplist API's Auth token endpoint for the token-exchange limit, and the Toplist API overview for the default per-credential data-endpoint limit) for exact numbers.