Ошибки, retries и лимиты

Формат ошибок /api/v1/*

Все Public API v1 endpoints возвращают единый JSON envelope:

{
  "error": {
    "code": "invalid_signal",
    "message": "Signal validation failed.",
    "traceId": "0HN8A1BC23DEF:00000001",
    "details": [
      {
        "field": "ttlMs",
        "code": "signal_expired"
      }
    ]
  },
  "requestId": "optional_request_correlation"
}

Поле	Назначение
error.code	стабильный machine-readable code
error.message	текст для диагностики; не используйте для ветвления программы
error.traceId	correlation server log; указывайте при обращении в поддержку
error.details	массив ошибок отдельных полей, обычно только для invalid_signal
requestId	присутствует, когда backend уже успел создать или найти signal request

Всегда принимайте неизвестный error.code как допустимое расширение API и сохраняйте полный response для диагностики.

Чтение ошибки в трёх языках

curl

curl --silent --show-error \
  --dump-header /tmp/tmpro-headers.txt \
  --output /tmp/tmpro-body.json \
  'https://tradingmonitor.pro/api/v1/signals/REPLACE_WITH_REQUEST_ID' \
  --header 'Authorization: Bearer tmpro_api_REPLACE_ME'

cat /tmp/tmpro-headers.txt
cat /tmp/tmpro-body.json

C#

using System.Text.Json;

using var response = await http.SendAsync(request);
var text = await response.Content.ReadAsStringAsync();

if (!response.IsSuccessStatusCode)
{
    using var json = JsonDocument.Parse(text);
    var root = json.RootElement;
    var error = root.GetProperty("error");
    var code = error.GetProperty("code").GetString();
    var traceId = error.GetProperty("traceId").GetString();
    var requestId = root.TryGetProperty("requestId", out var id)
        ? id.GetString()
        : null;
    var retryAfter = response.Headers.RetryAfter?.Delta;

    Console.Error.WriteLine(
        $"HTTP {(int)response.StatusCode}; code={code}; " +
        $"requestId={requestId}; traceId={traceId}; retryAfter={retryAfter}");
}

Python

response = requests.get(url, headers=headers, timeout=30)

if not response.ok:
    body = response.json()
    error = body.get("error", {})
    print(
        "HTTP", response.status_code,
        "code=", error.get("code"),
        "requestId=", body.get("requestId"),
        "traceId=", error.get("traceId"),
        "Retry-After=", response.headers.get("Retry-After"),
    )

Общие коды Public API v1

HTTP	Code	Значение
401	invalid_api_key	bearer key отсутствует, неверен, истёк, отозван или пользователь удалён
403	insufficient_scope	key действителен, но требуемый scope отсутствует
429	api_rate_limited	превышен rate limit API key или лимит неаутентифицированных попыток
500	internal_error	необработанная server error до начала response
503	public_api_disabled	оператор временно отключил Public API v1

Authorization должен иметь вид:

Authorization: Bearer tmpro_api_<secret>

Public API key нельзя заменить пользовательским JWT или sessionToken.

Коды signal endpoints

POST /api/v1/signals

HTTP	Code	Retry
400	invalid_idempotency_key	исправить header; автоматический retry того же неверного запроса бесполезен
400	malformed_json	исправить JSON
403	account_frozen	нет, требуется изменение состояния аккаунта
409	request_in_progress	да, повторить тот же body и key после Retry-After
409	idempotency_conflict	нет; key уже связан с другим body
409	idempotency_outcome_unknown	не отправлять новую торговую операцию; проверить terminal/broker
409	duplicate_signal_id	нет; signalId уже использован
413	request_body_too_large	уменьшить body
415	unsupported_media_type	установить Content-Type: application/json
422	invalid_signal	исправить поля по error.details
429	signal_rate_limit_exceeded	да, после Retry-After; account quota
429	daily_signal_limit_exceeded	только после сброса/изменения account quota
500	signal_processing_failed	не использовать новый key; outcome мог произойти

GET /api/v1/signals/{requestId}

HTTP	Code	Значение
404	request_not_found	request отсутствует или принадлежит другому пользователю

Validation details для invalid_signal

field	code	Причина
$	object_required	JSON root не является object
v	unsupported_version	отсутствует integer 1
signalId	invalid_length	отсутствует, пустой или длиннее 128 символов
type	invalid_length	отсутствует, пустой или длиннее 64 символов
cmd	invalid_length	отсутствует, пустой или длиннее 64 символов
ts	invalid_unix_milliseconds	значение отсутствует, не integer или вне диапазона Unix milliseconds
ts	signal_from_future	timestamp дальше допустимого clock skew
ttlMs	invalid_ttl	не integer либо вне 1..300000
ttlMs	signal_expired	ts + ttlMs уже в прошлом
ttlMs	timestamp_overflow	сумма timestamp и TTL вне допустимого диапазона
platform	required	поле отсутствует или пустое
platform	unsupported_platform	один из comma-separated tokens неизвестен
payload	object_required	payload отсутствует или не object
instanceId	invalid_length	если поле передано, оно пустое, не string или длиннее 128 символов

Ошибки terminal-specific payload, например неизвестный executionType или отсутствие limitPrice, возникают уже после принятия envelope. Они отражаются в executions[].status, reasonCode и terminal events, а не как HTTP 422.

Полный перечень terminal-specific полей и platform differences приведён в Справочнике торговых команд.

Коды exact cancel

HTTP	Code	Значение
400	invalid_idempotency_key	нет корректного единственного header
404	order_not_found	orderRef не найден, чужой или имеет недопустимый формат
409	order_not_cancellable	ордер не находится в отменяемом tracked state
409	terminal_unavailable	exact target сейчас недоступен или не поддерживает cancel capability
409	cancel_already_in_progress	предыдущая отмена ещё не финальна
409	idempotency_conflict	key уже использован для другого order

Финальный broker/terminal outcome является не HTTP-ошибкой, а executions[].cancel.status. См. Точная отмена ордера.

Коды Terminal Events API

HTTP	Code	Значение
400	invalid_terminal_source	query не задаёт точные platform, instanceId, accountName
400	invalid_event_cursor	Last-Event-ID повторён или длиннее 80 символов
404	terminal_source_not_found	source отсутствует среди активных sources пользователя
429	too_many_event_subscriptions	уже открыты 3 SSE subscriptions пользователя

replay_gap передаётся как SSE event после успешного HTTP 200, а не как HTTP error:

event: replay_gap
data: {"reason":"cursor_not_available"}

Ошибки login и API-key management

Endpoints /api/auth/login и /api/api-keys используют более простой legacy формат:

{
  "code": "invalid_credentials",
  "message": "Invalid email or password."
}

Он не содержит error, traceId или details.

Login

HTTP	Code	Значение
400	ASP.NET validation response	email/password не прошли model validation
401	invalid_credentials	неверный email или password
403	email_not_confirmed	email не подтверждён
429	rate_limit_exceeded	более 10 попыток в минуту для client partition

API-key management

Endpoint	HTTP	Code	Значение
все	401	может отсутствовать	JWT отсутствует, истёк или недействителен
все	403	business_plan_required	текущий plan не Business
create	400	invalid_name	имя не содержит 1–80 символов после trim
create	400	invalid_scopes	scope отсутствует, неизвестен или повторён
create	400	invalid_expiration	expiration не в будущем или дальше 365 дней
create	400	active_key_limit_reached	уже существует 5 активных keys
create	503	public_api_disabled	создание keys временно отключено
delete	404	может отсутствовать	key id не существует или принадлежит другому пользователю

Правила retry

Безопасный алгоритм для mutating request

1. До запроса создайте Idempotency-Key и сохраните его вместе с byte-identical signal body или точным orderRef.
2. При network timeout повторите тот же запрос с тем же key.
3. При request_in_progress дождитесь Retry-After и повторите тот же запрос.
4. При 429 дождитесь Retry-After, если он есть, затем примените exponential backoff с jitter.
5. При 5xx повторяйте только идемпотентно — с тем же key и теми же данными.
6. При idempotency_outcome_unknown или signal_processing_failed не создавайте новый key для той же торговой операции.

Для read-only GET безопасен обычный exponential backoff. Для SSE используйте Last-Event-ID и интервалы 1, 2, 5, 10 секунд.

Пример backoff

attempt 1: 1 s + jitter
attempt 2: 2 s + jitter
attempt 3: 5 s + jitter
attempt 4+: 10 s + jitter

Ограничивайте общее время retry и предоставляйте оператору traceId, requestId и Idempotency-Key без раскрытия API secret.

Текущие технические лимиты

Значения ниже соответствуют текущей backend-конфигурации и могут быть изменены оператором.

Лимит	Значение
Signal request body	65 536 bytes
JSON depth	16
Idempotency-Key	1–128 символов, без control characters
signalId	1–128 символов
Signal instanceId	1–128 символов, если поле передано; пустое значение запрещено
Максимальный ttlMs	300 000 ms
Допустимое будущее смещение ts	60 s
Активные API keys	5 на пользователя
Авторизованные Public API requests	1200/min на API key
Неавторизованные попытки	60/min на client partition
Login	10/min на client partition
Одновременные SSE streams	3 на пользователя
SSE instanceId	до 128 символов; пустая строка разрешена, параметр обязателен
SSE accountName	1–128 символов
Last-Event-ID	до 80 символов
Terminal active heartbeat window	120 s
Signal execution confirmation timeout	60 s
Cancel confirmation timeout	30 s
Signal idempotency retention	24 h
Stale processing timeout	5 min
Terminal event replay	1000 events или 10 min на пользователя
Pending live events	256 на SSE subscriber
Terminal event rawText	до 8192 символов
MT5 outgoing terminal event queue	до 2000 events или 10 min
Completed execution retention	30 days

Account signal quotas зависят от тарифного плана и применяются совместно к сигналам из Public API и других поддерживаемых каналов. SSE limit не влияет на количество подключённых устройств тарифного плана.

Безопасность логов

Не записывайте в application logs:

• полный tmpro_api_... key;
• пользовательский JWT;
• password;
• SignalR session token.

Можно записывать displayPrefix, requestId, executionId, orderRef, cancelRequestId, eventId, HTTP status, error.code и traceId.