Reference

Errors & Rate Limits

Standard error envelope, SDK exception mapping, and per tier rate limits.

Errors

All errors return a JSON envelope with code, message, and status. The SDK maps each code to a typed exception inheriting from MarketlensError.

Error codes

MARKET_NOT_FOUNDNotFoundError (404)

Market does not exist.

EVENT_NOT_FOUNDNotFoundError (404)

Event does not exist.

SERIES_NOT_FOUNDNotFoundError (404)

Series does not exist.

KEY_NOT_FOUNDNotFoundError (404)

API key not found.

DATA_NOT_AVAILABLENotFoundError (404)

No data for the requested query.

INVALID_PARAMETERInvalidParameterError (400)

Invalid or missing query parameter.

RANGE_TOO_LARGEInvalidParameterError (400)

Time range exceeds the allowed maximum for this endpoint.

CURSOR_EXPIREDInvalidParameterError (400)

Pagination cursor older than 24 hours.

UNAUTHORIZEDAuthenticationError (401)

Missing or invalid API key.

FORBIDDENForbiddenError (403)

Insufficient permissions.

TIER_LIMIT_REACHEDForbiddenError (403)

Feature not available on current tier.

RATE_LIMITEDRateLimitError (429)

Rate limit exceeded.

Non HTTP exceptions: ConnectionError on network failure, TimeoutError after 30s (configurable). The SDK retries 429 and 5xx errors with exponential backoff (default 2 retries, configurable via max_retries).

jsonResponse

{
  "error": {
    "code": "MARKET_NOT_FOUND",
    "message": "Market abc... not found",
    "status": 404
  }
}

python

from marketlens import MarketLens, NotFoundError, RateLimitError

try:
    book = client.orderbook.get("nonexistent-id")
except NotFoundError as e:
    print(e.code, e.message)
except RateLimitError as e:
    print(f"Retry after {e.retry_after}s")

Rate Limits

Dual gated: a per minute burst limit (RPM) and a daily request cap, both tracked per user across all API keys. Export endpoints (market history and reference trades) have a separate hourly export quota.

TierRPMDailyKeysExport/hrPrice

Free602,0001——

Pro720100,000560$39/mo

Enterprise1,800500,00025120$199/mo

Response headers

X-RateLimit-Limit

RPM limit for this user.

X-RateLimit-Remaining

Requests remaining in current 60s window.

X-RateLimit-Reset

Unix timestamp when window resets.

X-DailyLimit-Limit

Daily request cap.

X-DailyLimit-Remaining

Requests remaining today.

X-DailyLimit-Reset

Unix timestamp of next UTC midnight.

Retry-After

Seconds to wait (included on 429).