Supra Core API — Public Client Documentation

Chapter 06 — Error Codes

1. Purpose

This chapter explains Supra Core API error responses and the action a client should take. It does not expose internal exception text, stack traces, infrastructure, or private troubleshooting.

2. Error Envelope

Illustrative error response:

{
  "ok": false,
  "error": {
    "code": "<public-error-code>",
    "message": "<public-error-message>"
  }
}

Clients should inspect both:

the HTTP status code;
the public error.code.

Do not parse hidden meaning from the message text.

3. Public Status Reference

HTTP status	Meaning	Retry guidance
`200 OK`	Request succeeded	Process the documented `data` shape
`400 Bad Request`	Missing, invalid, or conflicting parameters	Correct the request first
`401 Unauthorized`	API key missing or not accepted	Fix authentication; do not loop
`404 Not Found`	Route is not available	Verify method and path
`405 Method Not Allowed`	Route exists but method is unsupported	Use documented `GET` method
`429 Rate Limited`	Applicable request allowance exceeded	Back off and reduce load
`500 Internal Error`	Service could not complete the request	Use bounded retry with backoff

4. `400 Bad Request`

Common public causes:

missing required parameter;
invalid integer;
unsupported granularity or sort value;
invalid BUY or SELL value;
invalid block or time range;
conflicting range boundaries.

Client action:

stop retrying the unchanged request;
validate parameters locally;
compare the request with the endpoint chapter;
retry only after correction.

5. `401 Unauthorized`

Common public causes:

missing X-API-Key or Bearer credential;
incorrect key value;
unavailable or inactive access;
expired access;
an IP address not allowed by the database-backed key policy.

Client action:

verify the key is loaded in the trusted backend;
verify the selected header is exactly X-API-Key or Authorization: Bearer;
verify no whitespace or quoting was added;
never log or display the key;
follow the approved access-support path if the problem remains.

6. `404 Not Found`

404 normally means the route is unavailable. It does not necessarily represent a missing market row or empty event history.

Documented data lookups can instead return:

data=null;
data=[];
HTTP 200.

7. `405 Method Not Allowed`

The documented public endpoints use GET. A different method can return 405.

Correct the method rather than retrying the same request.

8. `429 Rate Limited`

Pause, reduce concurrency, cache repeated reads, and retry with bounded backoff and jitter. Retry-After may not be present.

Do not treat 429 as an invalid key.

9. `500 Internal Error`

A 500 response can represent a temporary service problem.

Recommended behavior:

retry a small number of times;
use increasing delay and jitter;
stop after a bounded retry budget;
display a temporary-error state;
retain the last safe cached value with a stale label when appropriate.

10. Empty and Stale Data

These are not automatically errors:

an empty list;
a null pair lookup;
nullable fields;
data older than the client's freshness target.

Use endpoint timestamps and metadata to distinguish no data, stale data, and request failure.

11. Sanitized Support Report

Include:

UTC request time;
HTTP method;
endpoint path;
non-secret query parameters;
HTTP status;
public error code;
<request-id> when supplied;
a short expected-versus-observed description.

Exclude:

API keys;
authorization headers;
wallet private keys;
unrelated credentials;
complete secret-bearing commands.

12. Scope and Data Exposure

Error responses expose only the documented HTTP status, code, and message. They are sanitized and do not include stack traces or private diagnostics.

13. Chapter Summary

Handle errors by status and public error code. Correct 400, 401, 404, and 405 requests before retrying; back off on 429; use bounded retry for 500; and treat empty or stale data as separate client states.