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. The two 429 errors additionally carry structured fields inside the error object: limit, reset (Unix seconds), upgrade_url, and (for the daily budget) used.

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)

RPM burst limit exceeded. Auto-retried by the SDK. Carries limit, reset, and upgrade_url.

DAILY_BUDGET_EXCEEDEDDailyBudgetExceededError (429)

Daily event budget exhausted. Not auto-retried by the SDK. Carries used, limit, reset, and upgrade_url.

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). DAILY_BUDGET_EXCEEDED is not retried since the budget resets at midnight UTC.

jsonResponse

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

jsonResponse

{
  "error": {
    "used": 5000123,
    "limit": 5000000,
    "reset": 1783728000,
    "upgrade_url": "https://marketlens.trade/#pricing",
    "code": "DAILY_BUDGET_EXCEEDED",
    "message": "Daily event budget exhausted (5,000,000 events). Resets at midnight UTC.",
    "status": 429
  }
}

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 event-volume budget, both tracked per user across all API keys. Bulk exports are charged against the same event budget. One row equals one event.

TierRPMEvents/dayKeysPrice

Free1805M1—

Pro3,6005B5$39/mo

Enterprise10,800Unlimited25$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-EventBudget-Limit

Daily event-volume budget (events returned, summed across data endpoints).

X-EventBudget-Remaining

Events remaining in today's budget.

X-EventBudget-Reset

Unix timestamp of next UTC midnight.

X-Export-Events

Rows charged on an export response (markets and series export endpoints).

Retry-After

Seconds to wait (included on 429).