Errors

Error response format

All errors follow this structure:

{
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Parameter 'maxPrice' must be a positive integer.",
    "status": 400
  }
}

Error codes

Code	HTTP Status	Description
INVALID_PARAMS	400	Invalid or missing query parameters
MISSING_API_KEY	401	No Authorization header on a protected endpoint
INVALID_API_KEY	401	API key not recognized
EXPIRED_API_KEY	401	Subscription has ended
TIER_RESTRICTED	403	Endpoint requires a higher tier
NOT_FOUND	404	Resource not found
WEBHOOK_NOT_FOUND	404	Webhook subscription not found
QUOTA_EXCEEDED	429	Monthly request quota exceeded (including overage cap)
RATE_LIMIT_EXCEEDED	429	Per-minute rate limit exceeded
INTERNAL_ERROR	500	Unexpected server error
UPSTREAM_ERROR	502	Data source temporarily unavailable
SERVICE_DISABLED	503	API temporarily disabled via kill switch

Retry guidance

Status	Action
400	Fix the request parameters and retry
401	Check your API key
403	Upgrade your tier
404	Verify the resource ID exists
429	Wait for Retry-After seconds, then retry
500	Retry with exponential backoff
502	Retry after a brief delay
503	Service is temporarily down; retry later

Request tracing

Every response includes an X-Request-Id header (UUID v4). Include this ID in support requests for log correlation.