Errors

The Sharpe API uses RFC 9457 Problem Details for error responses. Every error is a flat JSON object with a machine-readable type URI, a human-readable title, the HTTP status code, a detailed message, and the request ID for debugging.

Error format

{
  "type": "https://www.sharpe.ai/errors/invalid_parameter",
  "title": "Invalid Parameter",
  "status": 400,
  "detail": "Invalid parameter \"type\": Invalid enum value. Expected 'current' | 'accumulated' | 'history'",
  "request_id": "req_abc123def456ghij",
  "doc_url": "https://www.sharpe.ai/docs/errors#error-codes",
  "suggested_action": "Check the parameter value against the endpoint documentation."
}

Error codes

Here is the complete list of error types returned by the Sharpe API. Use the type URI for programmatic branching and the status code for broad categorization.

Retry guidance

Not all errors are retryable. Here is how to handle each category:

4xx client errors — do not retry

These indicate a problem with your request. Fix the issue before retrying.

• 400 — Fix the invalid or missing parameter
• 401 — Check your API key is valid and not expired
• 403 — Verify your plan includes access to this endpoint, or check your monthly quota
• 404 — Verify the URL

429 rate limit — retry with X-RateLimit-Reset

When you hit a rate limit, use the X-RateLimit-Reset header to calculate when the current window expires.

HTTP/2 429
x-ratelimit-limit: 500
x-ratelimit-remaining: 0
x-ratelimit-reset: 1743062472
x-request-id: req_abc123def456

Wait until the Unix timestamp in X-RateLimit-Reset before sending the next request.

5xx server errors — exponential backoff

For 500, 502, and 503 errors, retry with exponential backoff:

1. Wait 1 second, then retry
2. Wait 2 seconds, then retry
3. Wait 4 seconds, then retry
4. Continue doubling up to a maximum of 30 seconds
5. After 5 retries, stop and alert your monitoring system

Troubleshooting

"My key works in cURL but fails in my app"

The most common cause is the Authorization header being stripped or malformed. Check that:

• The header is exactly Authorization: Bearer sk_live_... with a single space after Bearer
• Your HTTP client is not URL-encoding the header value
• No proxy or CDN between your app and www.sharpe.ai is stripping the Authorization header — if so, use X-API-Key instead

"I get 403 but my plan should include this endpoint"

A 403 can mean two things — check the type field in the error response:

• insufficient_scope — Your key was created with restricted scopes. Generate a new key with the required scope, or contact support to update scopes on the existing key.
• monthly_quota_exceeded — You have hit your plan's monthly request limit. Check your usage at GET /v1/usage and either wait for the monthly reset or upgrade your plan.

"I keep hitting 429 even at low volume"

Rate limits are per-minute fixed windows. If you send 30 requests in 2 seconds (within a single 60-second window), you will exhaust a Free tier limit instantly. Spread requests evenly across the minute or implement the backoff pattern from the rate limits guide.

"I get 502 or 503 intermittently"

These mean an upstream dependency (database or exchange API) is temporarily unavailable. Retry with exponential backoff. If the error persists for more than 5 minutes, check status.sharpe.ai or contact support with the X-Request-Id.

"Response data is empty or stale"

Some endpoints depend on cron jobs that populate data on a schedule (e.g., funding rates every 5 minutes, heatmap every 5 minutes, narratives every 30 minutes). If you query immediately after a new endpoint is deployed, data may not yet be populated. The updated_at or meta.timestamp fields indicate data freshness.