Keep your integration resilient.
Handle invalid queries, incomplete data, and temporary failures intentionally.
Check the HTTP status
Check response.ok before reading a success payload. Error shapes can differ between endpoint families and your deployment gateway, so retain the HTTP status and response body when reporting an issue.
The shared service error response contains error (a message), traceId, and optional details. Include the traceId when contacting support. Gateway responses may use a different shape.
400Invalid requestReview field types, metric names, cursor values, and the supported time windows. Fix the request before retrying.
401 / 403Access rejectedFor deployments with an access gateway, verify the credentials and permissions supplied during onboarding.
404Not foundCheck the service base URL, endpoint path, and entity identifier.
429Rate limitedReduce concurrency and honor Retry-After when the server provides it.
5xxService errorRetry eligible read queries with capped exponential backoff and jitter. Contact support if the failure persists.
Discovery query limits
Page size1–100Default: 20 markets per discovery page.
Requested deltas10 maximumNo more than five can use a custom since timestamp.
Filter depth5 levelsA maximum of 50 individual conditions across all nested filter groups.
Search200 charactersApplies to the discovery search string.
Tag lists50 per listApplies separately to tags_any, tags_all, and tags_none.
Request budgets
Your enterprise throughput and deployment capacity are agreed during onboarding. Individual endpoints also apply protective rate limits; a more expensive analytics request may have a lower limit than market discovery.
Reuse connections, cache shared query results, and avoid repeatedly polling unchanged pages. For event-driven updates, use the available stream service where it fits your workload.
Unavailable data is a valid state
A successful response can contain a missing delta, a nullable analytics field, or an empty result set. Check delta status values and preserve nulls in your application.
Holder metrics in market discovery are subject to availability controls. Start with volume, liquidity, and price; request holder fields only when they have been enabled for your deployment.