Error handling

These error conventions are shared across DataFlair's APIs on this site.

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.