Error codes

#The shape of an error

The detail is carried by the detail key. On validation errors, it names the offending value and, when a finite list exists, enumerates it.

{
  "detail": "Symbole 'PEPEUSDT' inconnu. Valeurs acceptees : BTCUSDT, ETHUSDT, ..."
}

Refusals tied to the plan have a fixed shape, set by the gateway: status, timestamp and detail, plus retry_after on time-based refusals (also present in the Retry-After header). The X-Deny-Reason header names the reason: rate, quota, family, websocket or key.

{
  "status": "error",
  "timestamp": 1775648290510,
  "detail": "Debit depasse : votre offre autorise un nombre limite de requetes par minute.",
  "retry_after": 1
}

The depth 403 is returned by the route itself, without X-Deny-Reason: its detail always starts with « Profondeur d’historique hors offre » and gives the maximum usable limit on that timeframe. The windows per plan are on the Usage limits page.

#HTTP codes

#Indicators

Validation follows a fixed order (timeframe, number of results, symbol, parsing of the indicators, ceiling rule, reading of the candles), and the first failure wins. A corrected body can therefore reveal a second error.

#WebSocket stream

Every impossible request receives an op: error message that says what was expected: the list of valid symbols, that of the channels, the bounds of depth. Three situations produce not an error but a closure:

The key is checked at the handshake, before the opening: a missing or invalid key, or a plan without the stream (Free), receives a 403 at the handshake, with X-Deny-Reason key or websocket. A 429 there signals too high an opening rate. Once connected, a channel whose family is not in the plan receives op: error (« canal … hors offre : la famille … n’est pas incluse dans votre abonnement ») and the whole subscription is refused. See Usage limits.

#MCP server

The errors follow a single pattern, Erreur (HTTP NNN) : message, so that an agent has only one case to recognise. Every tool call is judged as a REST request with the client’s key: a 403 for a family outside the plan or a 429 for quota come back as they are, with their detail. Two families are specific to it:

• Unknown metric: the message lists the forty-six valid metrics.
• Invalid targeting: two targets at once, missing target, wrong target, or a target passed to a whole-market metric. The error names the expected parameter, and it is raised before any network call.

A server fault gives rise to an automatic retry before being reported. A timeout returns Erreur (HTTP 504) after thirty seconds.

#Retry strategy

Not everything can be replayed. Replaying a faulty request produces exactly the same response, and consumes quota for nothing.

def should_retry(code: int) -> bool:
    """What is transient, and what never will be."""
    # 429 and 503 will pass: the server says when.
    if code in (429, 503):
        return True
    # 500: a fault on the service side, a retry makes sense.
    if code == 500:
        return True
    # 400, 403, 422: the request is at fault. Replaying it as is will
    # produce exactly the same response.
    return False

• Respect Retry-After rather than inventing a delay: the server knows when it will be ready.
• Bound the number of attempts. Three or four are enough: beyond that, the problem is not transient.
• Do not replay a 4xx, 429 aside. Correct the request.
• On the stream, reconnect with an increasing delay, and treat a 4003 closure as a signal of overload on the client side: reconnecting without changing the consumption will reproduce the cut.