Concepts
Errors and limits
An error says what went wrong in one sentence, whether the server looked, and whether trying again could help.
A call that could not run
A missing or invalid argument, or a tool name the server does not have, comes back as a result with isError: true and the reason in words. Fix the call and send it again.
{"jsonrpc":"2.0","id":1,"result":{"isError":true,"content":[
{"type":"text","text":"get_perps_history was not run: window: Input should be '1d', '7d', '30d' or '90d' (got '2y')."}]}}An answer that is an error
When the call is valid but the answer cannot be given, the content is an object with the reason and three fields a client can act on:
{
"error": "No entity matched 'ZZZZQQ'",
"error_kind": "bad_input",
"looked": false,
"retry": "other"
}| Field | Meaning |
|---|---|
error | What went wrong, in one sentence a reader can be shown. |
error_kind | One of the kinds below. |
looked | true only when the server searched and found nothing. false means it could not look, so the absence of data says nothing about the company. |
retry | later: a passing problem, try again shortly. other: change the request. never: the same request will get the same answer. |
Error kinds
| Field | Meaning |
|---|---|
bad_input | The request itself cannot be answered as asked, such as a company that matches nothing. retry: other. |
source_unavailable | A source the answer depends on did not respond. retry: later. |
not_covered | Nothing is held for this yet. The server did not look, so this is not an absence. retry: later. |
no_such_record | The server looked and there is nothing. The only kind with looked: true. retry: never. |
needs_licence | The data exists but cannot be served here. retry: never. |
not_built | This server does not offer that capability. retry: never. |
Rate limit
Each caller can make 60 requests a minute. Past that the server answers HTTP 429 with a Retry-After header giving the seconds to wait. A client making many calls in a loop should pace them.