Errors

All API errors use RFC 9457 application/problem+json responses.

---

Error envelope

{
  "type": "https://telegramtometatrader.com/problems/invalid-parameter",
  "title": "Invalid Parameter",
  "status": 400,
  "detail": "Unknown trade status 'foo'."
}

Field	Type	Description
type	string	A stable URI identifying the error type. Branch on this in code — never on detail.
title	string	Short human-readable label for the error type.
status	integer	HTTP status code, mirrored in the body for convenience.
detail	string	Optional. Specific message for this occurrence.

---

Status codes

Code	Meaning
200	OK
304	Not Modified (terminal trade/signal with matching If-None-Match)
400	Bad request — invalid or missing parameter
401	Authentication failed — missing, malformed, unknown, or revoked key
403	API access disabled for the account
404	Resource not found, or belongs to a different user
405	Method not allowed — the surface is GET-only
409	Conflict — a concurrent stream is already open for this key
429	Rate limit exceeded
503	Live container unavailable (stream only)

---

Example responses

Missing authentication:

{
  "type": "https://telegramtometatrader.com/problems/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Authorization header is required."
}

API access disabled:

{
  "type": "https://telegramtometatrader.com/problems/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "API access is not enabled for this account."
}

Invalid parameter:

{
  "type": "https://telegramtometatrader.com/problems/invalid-parameter",
  "title": "Invalid Parameter",
  "status": 400,
  "detail": "Unknown trade status 'foo'."
}

Not found:

{
  "type": "https://telegramtometatrader.com/problems/not-found",
  "title": "Not Found",
  "status": 404
}

Rate limited:

{
  "type": "https://telegramtometatrader.com/problems/rate-limited",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit exceeded. Retry after 12 seconds."
}

Concurrent stream conflict:

{
  "type": "https://telegramtometatrader.com/problems/conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "A stream is already open for this API key."
}

---

Handling errors in code

Branch on type (stable), not on detail (prose, may change):

resp = requests.get(f"{BASE}/trades", headers=headers)
if not resp.ok:
    err = resp.json()
    if err["type"].endswith("/unauthorized"):
        raise AuthError("check your API key")
    elif err["type"].endswith("/rate-limited"):
        time.sleep(int(resp.headers.get("Retry-After", 60)))
    else:
        raise ApiError(err["detail"])