Error format
Every error response is a flat RFC 9457 Problem Details object at the top level. There is nook field or nested error wrapper.
Properties
A URI reference that identifies the error type (e.g.,
https://www.sharpe.ai/errors/invalid_parameter). Use this for programmatic error handling.Error response
Error codes
Here is the complete list of error types returned by the Sharpe API. Use thetype URI for programmatic branching and the status code for broad categorization.
The provided API key is malformed or has been revoked. Double-check your
Authorization: Bearer or X-API-Key header.The API key has no active plan: the paid period and its 3 days of grace have ended, or it is a free key issued before 2026-11-11. Subscribe or renew at /dashboard/billing; the same key works again once the plan is active.
Your API key does not have the required scope to access this resource. Check the scopes assigned to your key.
You have exhausted your monthly request quota. Retryable: wait for the reset in the
Retry-After header, or upgrade your plan.You have exceeded your per-minute rate limit. Wait until the time indicated by the
X-RateLimit-Reset header.A dependency failed to respond. Used only by endpoints that do not yet carry the freshness envelope (their reference pages list
502). Retry with exponential backoff.A data source or our data store is temporarily unavailable, and nothing stored could be served instead. The
detail names the source (for example GoPlus Security is unavailable.), and Retry-After says when to try again: 60 seconds for an upstream source, 30 for the data store. Every endpoint that carries the freshness envelope answers an outage this way; 502 is not used there.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 return429. 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 atX-RateLimit-Reset.monthly_quota_exceeded: the monthly quota is exhausted. It reopens atX-Quota-Reset, andRetry-Aftercarries the seconds until then.
429 response headers
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 thanRetry-After when it is present):
- Wait 1 second, then retry
- Wait 2 seconds, then retry
- Wait 4 seconds, then retry
- Continue doubling up to a maximum of 30 seconds
- After 5 retries, stop and alert your monitoring system
Always include the
X-Request-Id from the failed response when contacting support.
This lets us trace the exact request through our infrastructure.Troubleshooting
”My key works in cURL but fails in my app”
The most common cause is theAuthorization header being stripped or malformed. Check that:
- The header is exactly
Authorization: Bearer sk_live_...with a single space afterBearer - Your HTTP client is not URL-encoding the header value
- No proxy or CDN between your app and
www.sharpe.aiis stripping theAuthorizationheader. If one is, useX-API-Keyinstead
”I get 403 but my plan should include this endpoint”
A 403 is alwaysinsufficient_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 thetype 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 the Hobbyist plan’s 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 atGET /v1/usage, then either wait out theRetry-Afterwindow 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 forRetry-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 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.
When the data was current: the dataset’s own time (the newest live row, the snapshot or refresh time, or the fetch time), never the response time.
null when unknown.as_of plus the freshness SLA. Past this instant the data is stale, however long a copy was cached: re-judge a stored copy against it.The dataset’s SLA: its writer’s cadence plus one skipped run.
GET /v1/meta/coverage lists each product’s datasets with their cadence and SLA.fresh within the SLA, stale past it, unknown when as_of is null, judged when the answer was built (meta.generated_at).degraded when this read was incomplete: a leg timed out or failed, a row budget was hit (meta.truncated), or a fallback answered (meta.served_from: "last-good" or a stored snapshot). ok otherwise.The dataset read, where the rows came from, the upstream sources behind them, how complete the stored data is (
coverage.used of coverage.expected, drops by reason), what the read could not do, and when the answer was built.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.
