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)

RPM burst limit exceeded. Auto-retried by the SDK.

DAILY_BUDGET_EXCEEDEDDailyBudgetExceededError (429)

Daily event budget exhausted. Not auto-retried by the SDK.

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
  }
}

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

Free1801M1—

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).