What this page promises, and what it does not#
Onekey runs on a best-effort basis. There is no uptime guarantee, service level agreement or service credit on the free tier or on standard credit packs, and beta endpoints carry no reliability target at all (see the SLA). This page describes how failures are treated, which you can check in the docs and in every response, and where to look at live state. It quotes no uptime percentage and shows no incident history, because none is published yet.
Stable and beta#
Every endpoint carries one of two statuses, in the registry and on its page:
| Status | Meaning | Count today |
|---|---|---|
| stable | Verified against the live source and monitored. | 1,292 |
| beta | Built from documented behaviour but not yet verified against the live source, so fields or availability may change. Failed calls are refunded either way. | 703 |
Total: 1,995 endpoints across 294 platforms, counted from the registry when this page is rendered. The status endpoint below also draws on the last saved verification sweep of stable endpoints.
When a call fails#
| Situation | Cost | What you get |
|---|---|---|
Source failed or timed out (502) | Free (refunded) | A typed error with doc_url; retry with backoff. |
Record not found (404) | Free (reserved, then refunded) | Remembered as "not found" for 1 to 5 minutes, so a repeat is instant and free. |
Invalid parameters (422) | Free (rejected before any charge) | The error names the parameter. |
Bad key (401), rate limited (429) | Free | Retry-After on 429. |
| Answer served from cache, fresh or stale | Free | cached, stale and age_s in metadata. |
| A call you cannot afford | Nothing charged | INSUFFICIENT_CREDITS, before any work. |
An empty list from a search that succeeded is a real answer and is charged. More in Credits & pricing and Refunds.
Cache and stale-serve#
Recent answers are remembered per endpoint. Fresh answers are served free. Stale ones (older than the fresh window) are served instantly and free with stale: true while Onekey refreshes them in the background. If the source is down when a refresh is needed and a recent enough copy exists, you get that copy marked stale instead of an error; if not, you get a 502 and are not charged. Free when served from cache (0.2 credit for a cached response over 100 KB). Simultaneous identical requests are merged into one fetch. Each endpoint page states its own windows. See Caching.
Retries that cannot double-charge#
Send an Idempotency-Key header on any billed call your code might send twice. The same key on the same request is billed at most once; a repeat within 24 hours gets the stored answer at 0 credits, marked idempotent_replay: true. A failed attempt releases the key. See Idempotency. Use it together with the retry rules in Errors: retry 429 after Retry-After, retry 500/502 with backoff, and never retry 400, 401, 402, 404 or 422.
Rate limits#
By default each API key can make 600 requests per minute and have 50 requests in flight at once, refilled continuously. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, and a 429 carries Retry-After. A key can also carry its own credit limit, so a runaway job stops at a number you chose while your other keys keep working. See Rate limits.
Where to see live state#
- The status page checks the API every 5 seconds while it is open.
GET https://api.onekey.dev/v1/statusis public: no key, no credits. It returns each platform asok,degraded,downorunknown, refreshed every 30 seconds, from Onekey's own fetches to each platform.unknownmeans "not observed recently", not "down", and today most platforms areunknownuntil something is fetched from them. See the status endpoint docs.- Every response says what happened to it:
metadata.cached,stale,age_s,credits_charged,request_id. Quote therequest_idwhen you contact support. - Universal search, reports and monitors show per-leg status and error types, so one failing platform never hides behind an overall success.
What we measure, and what is not published#
We observe fetch outcomes per platform (the circuit breakers behind the status endpoint) and run verification sweeps of stable endpoints. We have not yet published success rates, latency percentiles or uptime, and this page will not state any until there is a measured series to point at, with its window.