Errors
The error codes of the Local API, the errors the clients raise and the close codes of the stream.
Every failed request carries a stable code. Rely on the code: the message is
for a human and may change. Over HTTP the error is the body of the answer:
{"error": {"code": "not_found", "message": "no such operation"}}.
Error codes
| Code | HTTP | When | What to do |
|---|---|---|---|
unauthorized | 401 | The token is missing or wrong, or the API is off | Copy the current token and check the switch |
forbidden | 403 | The request comes from a browser page, or its host is not 127.0.0.1 or localhost | Call from a program on the same machine |
forbidden_scope | 403 | The token lacks the scope of the call | Check meta().scopes |
not_found | 404 | Unknown address or connection, or no connection for the instrument | Check the instrument and connections() |
invalid_request | 400 | A bad parameter, or an instrument the catalogue does not know | Fix the parameter |
unsupported | 501 | MOEX, a terminal built without market data, or a setting the API cannot write | Do not retry |
not_active | 409 | Clusters or leverage of the instrument are not loaded yet | Call again in a few seconds. For leverage, open the instrument in the terminal |
not_tradable | 409 | The connection is disabled, read-only or has no credentials | Pick a trading connection |
rate_limited | 429 | A limit is exceeded | Wait a moment and call again |
unavailable | 503 | The exchange or the terminal did not answer, or there is no data yet | Call again later |
The stream uses the same codes. New codes can be added inside v1.
Catch an error
from spectre_terminal import ApiError
try:
book = terminal.orderbook("binance:futures:BTCUSDT", depth=20)
except ApiError as error:
print(error.status, error.code, error.message)The clients raise these errors.
| Python | TypeScript | When |
|---|---|---|
ApiError | ApiError | The terminal answered with a code from the table above |
TokenMissing | TokenMissingError | No token was passed or set in SPECTRE_LOCAL_API_TOKEN |
LocalApiDisabled | LocalApiDisabledError | The Local API is switched off |
TerminalUnreachable | TerminalUnreachableError | The terminal is not running or listens on another port |
IncompatibleTerminal | IncompatibleTerminalError | The client does not support the API version of the terminal |
StreamRequestError | StreamRequestError | A subscribe or unsubscribe was refused |
StreamClosed | StreamClosedError | The terminal closed the stream |
All of them extend SpectreTerminalError. The token never appears in an
error text.
Stream close codes
| Code | Why | What to do |
|---|---|---|
1001 | The API was switched off or the token was reissued | Reconnect with the current token |
1006 | The connection was lost | Reconnect |
4008 | Your program did not read for more than 5 seconds | Read faster or subscribe to less |
4029 | The token already has 8 stream connections | Reuse a connection |
To reconnect in code, see Reconnect.