DocsPricingContact Us
Log inGet Started

Error Codes

The PolyTest API uses standard HTTP status codes. All error responses return a JSON body with an error field describing the issue.

Error response format: All errors return a JSON object with a single "error" key containing a human-readable message. The HTTP status code indicates the error category.
400Bad Request

The request is malformed or missing required parameters.

{ "error": "timestamp query parameter is required" }

Common Causes

  • Missing a required query parameter
  • Invalid parameter format (e.g. non-ISO 8601 timestamp)
  • Invalid parameter value out of allowed range
401Unauthorized

Authentication failed — the request has no valid credentials.

{ "error": "Invalid API key" }

Common Causes

  • Missing X-API-Key header or Authorization header
  • API key does not exist or is invalid
  • API key has been revoked
  • API key has expired
  • JWT token is invalid or expired
403Forbidden

The credentials are valid but lack permission for this action.

{ "error": "Admin access required" }

Common Causes

  • Attempting to access admin-only endpoints (sync, seed) without admin privileges
  • API key scope does not include the required permission
404Not Found

The requested resource does not exist.

{ "error": "Market not found" }

Common Causes

  • Market ID does not exist
  • Market slug does not match any record
  • No snapshot found within ±2 seconds of the given timestamp
429Too Many Requests

Rate limit exceeded. Back off and retry after the indicated time.

{ "error": "Rate limit exceeded" }

Common Causes

  • Exceeded requests-per-minute limit for your plan tier
  • Burst limit exceeded (too many requests in a short window)
500Internal Server Error

An unexpected error occurred on the server. These are rare — if persistent, contact support.

{ "error": "Internal server error" }

Common Causes

  • Database connectivity issue
  • Upstream service failure
  • Unexpected server-side exception

Handling Errors

Client Errors (4xx)

Do not retry automatically. Fix the request parameters, authentication, or check that the resource exists before retrying.

Server Errors (5xx)

Safe to retry with exponential backoff. Start with a 1-second delay and double on each attempt up to 3 retries.

import time
import requests

def api_request(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)

        if response.status_code == 429:
            wait = int(response.headers.get("Retry-After", 2 ** attempt))
            time.sleep(wait)
            continue

        if response.status_code >= 500:
            time.sleep(2 ** attempt)
            continue

        return response

    raise Exception("Max retries exceeded")