ReqKey.docs
Reference

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

200OKRequest succeeded.
201CreatedResource created successfully.
202AcceptedAccepted for processing (e.g. /ingest).
400Bad RequestInvalid body or a missing required field.
401UnauthorizedMissing or invalid rootKey.
402Payment RequiredThe consumer’s credit limit is exceeded.
403ForbiddenWrong project, disabled key/consumer, or API not allowed.
404Not FoundThe referenced resource does not exist.
409ConflictResource already exists (e.g. duplicate apiId).
410GoneThe project is soft-deleted.
429Too Many RequestsAnalytics rate limit hit — check Retry-After.
500Server ErrorAn internal error — safe to retry with backoff.

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 and 403 for a disabled key/consumer or an out-of-scope API. Always branch on the valid field, not just the status.

Don’t treat 402 / 403 as outages
These mean the caller’s key can’t proceed (out of credits, disabled, wrong API) — not that ReqKey is down. Surface them to your customer; retrying won’t help until the underlying issue is fixed.

Rate limiting

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.

Read Retry-After and back off before retrying. If no limit is configured for a customer, analytics access is unlimited.

PreviousPlatform