Prediction Hunt logoPrediction Hunt
Live
Prediction Hunt/ API
API Documentation
REST API / REST API / Errors

Error Reference

Every v2 API error returns the same envelope. The code field is a stable machine-readable string you can branch on; error and message are human-readable. Internals (stack traces, raw exception messages) are never returned.

Stuck on an error?

Include the code from the response and a rough timestamp — that's all we need to investigate.

Ask in Discord
#api-discussion — usually fastest
Email support
api@predictionhunt.com

Browse error codes

Returned when the API key is missing, invalid, or not authorized for an endpoint.

auth.endpoint_blocked403
API Key not authorized for this endpoint.
Your current plan does not include access to this endpoint. Upgrade to use it.
auth.expired_api_key403
API Key has expired.
Renew your subscription or generate a new key.
auth.inactive_api_key403
API Key is inactive or revoked.
Contact support or generate a new key.
auth.internal_check_failed500
Internal server error during authentication.
An unexpected error occurred while verifying your API key. Please try again or contact support.
auth.invalid_api_key403
Invalid API Key.
The provided API key was not found.
auth.missing_api_key401
Authentication required.
Provide an X-API-Key header or api_key query parameter.

Returned when you exceed a per-second, monthly, or per-endpoint quota. Honor the Retry-After header.

rate_limit.exceeded_group429
Endpoint quota exceeded.
You have exceeded the monthly request quota for this endpoint group on your plan. Upgrade your plan to increase the limit.
rate_limit.exceeded_month429
Monthly quota exceeded.
You have exceeded your monthly request quota. Upgrade your plan or wait until the quota resets.
rate_limit.exceeded_second429
Rate limit exceeded.
You have exceeded your per-second rate limit. Wait for the duration indicated by the Retry-After header before retrying.

400-class errors. The request was malformed — fix and retry.

validation.invalid_alert_type400
Invalid alert_type
The provided alert_type is not supported.
validation.invalid_bucket400
Invalid bucket
The provided bucket is not supported.
validation.invalid_cursor400
Invalid cursor
The pagination cursor is invalid for the current filter set.
validation.invalid_date_format400
Invalid date format
Use ISO 8601 format (e.g. 2026-03-20T00:00:00Z).
validation.invalid_enum400
Invalid parameter
Parameter value is not one of the allowed options.
validation.invalid_eth_address400
Invalid wallet address
Wallet address must be a 0x-prefixed 40-char hex string.
validation.invalid_interval400
Invalid interval
The provided interval is not a supported bucket size.
validation.invalid_order400
Invalid order
The provided sort order is not supported.
validation.invalid_param400
Invalid parameter
One of the request parameters is invalid.
validation.invalid_platform400
Invalid platform
The provided platform is not supported by this endpoint.
validation.invalid_range400
Invalid range
The provided time range is not valid.
validation.invalid_side400
Invalid side
The provided side is not supported.
validation.invalid_sport400
Invalid sport
The provided sport is not recognized by this endpoint.
validation.invalid_status400
Invalid status
The provided status filter is not valid for this endpoint.
validation.invalid_timestamp400
Invalid timestamp
The provided timestamp is not valid.
validation.missing_param400
Missing parameters
A required parameter is missing.
validation.range_too_large400
Range too large
The requested time range exceeds the maximum supported for this bucket size.
validation.too_many_items400
Too many items
The request exceeds the maximum number of items allowed.
validation.too_many_params400
Too many parameters
Provide fewer mutually-exclusive parameters.
validation.unsupported_platform400
Unsupported platform
The platform is not supported by this endpoint.

404-class errors. The resource doesn't exist or hasn't been provisioned.

not_found.no_data_near_timestamp404
No data near timestamp
No price data is available near the requested timestamp.
not_found.no_recent_price_data404
No recent price data
No recent price data is available for this market.
not_found.orderbook404
Orderbook not available
No orderbook data is available for this market.
not_found.resource404
Not found
The requested resource does not exist.
not_found.token_resolution404
Token resolution failed
Could not resolve outcome tokens for the requested market.
not_found.volume_aggregate503
Volume aggregate not provisioned
The continuous aggregate backing this endpoint has not been provisioned on this deployment.
not_found.wallet404
Wallet not found
The requested wallet has no public trading activity.

Errors returned by a third-party provider (Polymarket, Kalshi, etc.) that we proxy.

upstream.error502
Upstream error
An upstream provider returned an error.
upstream.rate_limited429
Upstream rate limit
An upstream provider returned a rate-limit error. Retry after the Retry-After delay.

Unexpected server-side failures. The internal details are scrubbed from the response — quote your request and we'll investigate.

internal.unexpected500
Internal server error
An unexpected error occurred. Please try again, or reach out in our Discord #api-discussion channel: https://discord.com/channels/1408572088868012135/1489979077933924434