Errors & status codes
ReqKey uses conventional HTTP status codes and a single, predictable error shape. Read the status first, then the message for the specifics.
Error shape
Every failure returns a JSON object with a human-readable error field:
{
"error": "Error message describing what went wrong"
}Status codes
Validation responses
/key/validate is special: a rejected key is still a successful HTTP call. A missing or unknown key returns 200 with { "valid": false }, while blocking conditions use real error codes — 402 for no credits, 403 for a disabled key/consumer or an out-of-scope API, and 429 when the consumer is over its rate limit. Always branch on the valid field, not just the status.
Rate limiting
Two separate limits can produce a 429: a consumer’s own rate limit on /key/validate, and the per-customer limit on analytics endpoints. Both send Retry-After — read it and back off before retrying.
Consumer rate limits
A consumer’s rateLimit of { limit, window } allows limit validations per window seconds — a sliding window shared by every key the consumer owns. Set it on /consumer/create or /consumer/update, or inherit it from a plan. When the consumer exceeds it, /key/validate returns 429 with { "valid": false, "rateLimited": true } and these headers:
Retry-AfterSeconds until a retry can pass.X-RateLimit-LimitThe configured limit.X-RateLimit-RemainingAlways 0 on a 429.X-RateLimit-WindowThe configured window, in seconds.Analytics rate limits
Analytics endpoints are rate-limited per customer. When you’re throttled you get a 429 plus headers describing the window:
X-RateLimit-LimitTotal requests allowed in the window.X-RateLimit-RemainingRequests remaining.X-RateLimit-ResetUnix timestamp when the limit resets.Retry-AfterSeconds to wait — only present on 429 responses.If no limit is configured for a customer, analytics access is unlimited.