Error Codes

Every error response from the Kwery API returns a consistent JSON body and an appropriate HTTP status code.

Error response format

{
  "error": "error_code",
  "message": "Human-readable description.",
  "required_tier": "pro",
  "upgrade_url": "https://kwery.xyz/pricing"
}

The required_tier and upgrade_url fields are only present on plan_required errors.

Rate limit responses

Rate-limited responses include a Retry-After header with the number of seconds to wait before retrying.

HTTP/1.1 429 Too Many Requests
Retry-After: 12
Content-Type: application/json

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Retry after 12 seconds."
}

Reference table

HTTP Status	Code	Description	What to do
401	`invalid_api_key`	Missing, malformed, or unknown key	Check key, regenerate in Dashboard
401	`api_key_revoked`	Key revoked or expired	Create new key
402	`credits_exhausted`	Monthly credits depleted	Upgrade or wait for reset
403	`account_suspended`	Account suspended/deleted	Contact support
403	`plan_required`	Endpoint/feature locked for your tier	Upgrade plan
429	`rate_limit_exceeded`	RPM or RPH exceeded	Respect Retry-After, implement backoff
400	`invalid_param`	Bad query parameter	Check values and docs
500	`internal_error`	Server error	Retry with backoff

Handling errors

Parse the error field to determine the error type programmatically.
For 429 responses, always respect the Retry-After header and implement exponential backoff.
For 402 responses, call GET /v1/limits with your key in the X-API-Key header (free, no credit cost) to check remaining credits.
For 500 errors, retry up to 3 times with exponential backoff before alerting.