Skip to main content

​
Error Response Format

All API errors use the same top-level shape: 
{
  "error": "human-readable message",
  "code": "machine_readable_code",
  "retryable": false,
  "validation_errors": ["optional detail"]
}
FieldTypeDescription
errorstringHuman-readable error message
codestringMachine-readable error code
retryablebooleanWhether the request can be safely retried
validation_errorsstring[]Optional field- or item-level validation details
tierstringPresent on some 429 responses
limit_qpsnumberPresent on some 429 responses

​
Error Codes

CodeMeaning
unauthorizedMissing or invalid API key
forbiddenAuthenticated, but not permitted for this action
credentials_requiredExchange credentials not configured
authentication_failedExchange-level auth failure
missing_parameterRequired parameter missing
bad_requestInvalid request format or parameters
validation_errorStructured validation failure
exchange_not_foundUnknown exchange identifier
market_not_foundMarket does not exist
event_not_foundEvent does not exist
event_not_resolvableEvent selector cannot be resolved
order_not_foundOrder does not exist
not_foundGeneric resource not found
insufficient_fundsNot enough balance for the operation
not_supportedExchange does not support this operation
rate_limit_exceededPer-second request limit exceeded
monthly_limit_exceededMonthly request quota exhausted
service_unavailableUpstream exchange temporarily unavailable
session_signer_expiredSession signer expired and must be refreshed
internal_errorUnexpected server failure

​
HTTP Status Codes

StatusMeaningAction
400Bad request or validation failureFix the request and retry
401Missing or invalid API keyCheck X-API-Key
402Insufficient fundsFund the exchange account
403Forbidden or exchange credential issueCheck permissions and exchange credentials
404Resource not foundVerify the identifiers you passed
429Rate limitedHonor Retry-After and retry
500Internal server errorRetry; contact support if persistent
501Unsupported operationCheck exchange capabilities
503Upstream exchange or snapshot unavailableRetry with backoff

​
Rate Limiting and Quota Headers

Successful responses may include:
HeaderDescription
x-parsec-tierYour API key tier
x-ratelimit-monthly-limitMonthly request quota
x-ratelimit-monthly-remainingRemaining monthly requests
x-ratelimit-monthly-resetUnix timestamp when monthly quota resets
Rate-limited responses also include:
HeaderDescription
Retry-AfterSeconds to wait before retrying
Builder impersonation requests include additional per-user and pool headers:
HeaderDescription
x-ratelimit-user-limitEnd-user QPS limit
x-ratelimit-user-remainingRemaining end-user tokens
x-ratelimit-pool-limitBuilder pool QPS limit
x-ratelimit-pool-remainingRemaining builder pool tokens

​
Examples

​
Structured Validation Failure

{
  "error": "invalid request",
  "code": "validation_error",
  "retryable": false,
  "validation_errors": [
    "scope=market_batch requires parsec_ids or external_market_keys",
    "parsec_ids may contain at most 100 items"
  ]
}
Use validation_errors as the authoritative list of what to fix.

​
Rate Limit Response

{
  "error": "rate limit exceeded",
  "code": "rate_limit_exceeded",
  "retryable": true,
  "tier": "free",
  "limit_qps": 5
}

​
Monthly Quota Exceeded

{
  "error": "monthly request limit exceeded",
  "code": "monthly_limit_exceeded",
  "retryable": false
}

​
Historical Data Tier Limit

{
  "error": "historical data limited to 5 days on the free tier — upgrade for more",
  "code": "bad_request",
  "retryable": false
}

​
SDK Error Handling

import ParsecAPI from 'parsec-api';

const client = new ParsecAPI();

try {
  await client.markets.list({ exchanges: ['kalshi'], search: 'bitcoin' });
} catch (err) {
  if (err instanceof ParsecAPI.APIError) {
    console.log(err.status);
    console.log(err.message);
  }
}

​
Next Steps

API Overview

Base URL, authentication, identifiers, and pagination.

List Markets

See the discovery-first market lookup contract.