Error Handling

API error codes and how to handle them

Error Handling

The API uses standard HTTP status codes and returns structured error responses.

Error response format

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description"
  },
  "timestamp": "2026-03-27T12:00:00Z"
}

Error codes

400 Bad Request

Code	Description	Fix
VALIDATION_ERROR	Invalid parameters	Check required params like coin

# Missing required 'coin' parameter
curl -H "X-API-Key: KEY" "https://api.polyhistorical.com/v1/markets"
# => 400: "coin parameter is required"

401 Unauthorized

Code	Description	Fix
UNAUTHORIZED	Missing or invalid API key	Check your X-API-Key header

403 Forbidden

Code	Description	Fix
TIER_ACCESS_DENIED	Feature requires higher plan	Upgrade at polyhistorical.com/pricing
BACKTEST_AI_REQUIRED	Backtest AI Agent BETA requires Pro or Enterprise	Upgrade to Pro or contact Enterprise sales

Starter API keys cannot access Binance Spot or Binance Futures endpoints. These endpoints require Pro or Enterprise.

The response includes upgrade details:

{
  "error": {
    "code": "TIER_ACCESS_DENIED",
    "message": "Your STARTER plan only allows access to the last 7 days of data. Upgrade to PRO for extended history.",
    "details": {
      "required_tier": "PRO",
      "current_tier": "STARTER",
      "upgrade_url": "/v1/account/billing"
    }
  }
}

404 Not Found

Code	Description	Fix
RESOURCE_NOT_FOUND	Market not found	Verify the slug exists via list markets

429 Too Many Requests

Code	Description	Fix
RATE_LIMIT_EXCEEDED	Daily limit exceeded	Wait for reset or upgrade plan
BACKTEST_AI_QUOTA_EXCEEDED	Monthly Backtest AI Agent BETA quota reached	Wait for next monthly reset or contact Enterprise sales

Response includes Retry-After header (seconds until reset).

See Rate Limits for details.

500 Internal Server Error

Code	Description	Fix
INTERNAL_ERROR	Unexpected server error	Retry after a moment. If persistent, contact support.

Best practices

1. Check status codes first

   Use the HTTP status code to determine the error category before parsing the body.

2. Read the error message

   The message field contains actionable information about what went wrong.

3. Implement retries for 429 and 5xx

   Use exponential backoff. Respect the Retry-After header for 429 responses.

4. Don't retry 400/401/403

   These are client errors that won’t resolve on retry. Fix the request instead.