Error Handling

Error format, status codes, and troubleshooting.

Error Handling

All errors return a consistent JSON structure with an HTTP status code, error code, and human-readable message.

Error Format

{
  "error": {
    "code": "ERROR_CODE",
    "message": "What went wrong",
    "request_id": "req_abc123"
  }
}

Every error includes the request_id from the X-Request-Id response header, making it easy to trace issues in logs.

Error Codes

Code	HTTP Status	When It Happens
BAD_REQUEST	400	Invalid parameters, malformed input, failed validation
UNAUTHORIZED	401	Missing API key, invalid key, or revoked key
FORBIDDEN	403	Key scope doesn’t allow this operation (e.g., read key trying POST)
NOT_FOUND	404	Market, token, or resource doesn’t exist
RATE_LIMITED	429	Too many requests — check X-RateLimit-Remaining header
IP_BLOCKED	403	Your IP has been blocked (excessive failed auth or abuse)
INTERNAL_ERROR	500	Server-side error — retry with backoff

Troubleshooting

400 Bad Request

Check your request parameters:

• Market IDs must be valid UUIDs
• Token IDs must be numeric strings (Polymarket uint256 values)
• Addresses must be valid Ethereum addresses (0x + 40 hex chars)
• Pagination: limit must be 1–100, offset must be ≥ 0
• Search queries max 200 characters, no SQL injection patterns
• Candle resolution must be one of: 1m, 5m, 15m, 1h, 4h, 1d

401 Unauthorized

• Verify your API key is correct and starts with gf_
• Check you’re sending it in the X-API-Key header, Authorization: Bearer header, or api_key query parameter
• Your key may have been revoked — generate a new one

403 Forbidden

Two possible causes:

1. Scope violation — your key’s scope doesn’t allow this HTTP method. read keys can only GET. Use a write or admin key for mutations.
2. IP blocked — your IP was blocked due to excessive failed auth attempts or abuse. Contact support.

429 Rate Limited

You’ve exceeded your per-minute rate limit. Check the response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0

To fix:

• Reduce request frequency
• Use WebSocket for real-time data instead of polling
• Cache responses where appropriate
• Upgrade your key scope for higher limits

500 Internal Error

Something went wrong on our end. These are rare but can happen during:

• Database connection issues
• Redis timeouts
• Blockchain node sync delays

What to do: Retry with exponential backoff (1s → 2s → 4s → max 60s). If the error persists, check the status page.