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. Use GET /v1/futures/coins or GET /v1/meta/coverage to discover valid values."
}

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.

An answer the server could only partly build is not an error: it is a 200 whose meta.runtime_status is degraded (with X-Data-Partial naming the reads that were cut short, or X-Data-Fallback when the server's last good answer or a stored snapshot stands in). Degraded answers are never cached, so a retry after a short wait can return the complete one. See Data freshness.

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: Create a key with the scopes this endpoint requires
• 404: Verify the URL

429 rate limit and quota: retry after the reset

Both limit rejections are retryable and both return 429. Use Retry-After when present, or X-RateLimit-Reset for the per-minute window:

• rate_limit_exceeded: the per-minute window is exhausted. It reopens at X-RateLimit-Reset.
• monthly_quota_exceeded: the monthly quota is exhausted. It reopens at X-Quota-Reset, and Retry-After carries the seconds until then.

HTTP/2 429
x-ratelimit-limit: 30
x-ratelimit-remaining: 0
x-ratelimit-reset: 1743062472
retry-after: 12
x-request-id: req_abc123def456

Wait for Retry-After seconds, or 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 (and never sooner than Retry-After when it is present):

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 one is, use X-API-Key instead

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

A 403 is always insufficient_scope: the key was created with restricted scopes. Generate a new key with the required scope, or contact support to update scopes on the existing key. Quota exhaustion is not a 403. It returns a retryable 429.

"I keep hitting 429 even at low volume"

A 429 can mean two things. Check the type field in the error response:

• rate_limit_exceeded: 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.
• monthly_quota_exceeded: You have hit your plan's monthly request limit, so every request fails until the quota resets. Check your usage at GET /v1/usage, then either wait out the Retry-After window or upgrade your plan.

"I get 502 or 503 intermittently"

These mean an upstream dependency (a data source or our data store) is temporarily unavailable and nothing stored could be served instead. Wait for Retry-After, then retry with exponential backoff. If the error persists for more than 5 minutes, 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 (for example, current funding rates every 5 minutes and the heatmap cache every 3 hours and narrative caches every 4 hours). If you query immediately after a new endpoint is deployed, data may not yet be populated. Read the freshness envelope below: it states the data's age and whether it is past its SLA.

Data freshness

Every endpoint served by the freshness envelope (all of v1 except /v1/funding/rates, /v1/funding/coins, /v1/futures/data, /v1/futures/coins, /v1/market/derivatives-overview, /v1/arbitrage/spot-perp, /v1/arbitrage/cross-exchange, /v1/rug-check/trending, /v1/analytics/query and the system routes) says how fresh its answer is, in meta and in headers. A successful answer that is stale or incomplete is still a 200: read these fields instead of the status code.

The same facts travel as headers on every free and v1 answer of these endpoints: X-Data-As-Of, X-Data-Stale-After, X-Data-Stale (true unless fresh), X-Data-Status (fresh, stale, degraded or fallback), X-Freshness-Sla-Seconds, X-Data-Source (comma-separated source ids) and X-Data-Coverage (used/expected). Free endpoints whose body is a JSON object carry the fields in their own meta key too; a bare-array body has the headers only.