Ошибки

Конверт ошибок, коды статусов, request id и правила ретраев.

Конверт

Каждая ошибка — Cloud API или JSON-режим CLI — несёт машиночитаемый конверт с request_id. Указывайте его в запросах поддержки:

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "error": {
    "type": "unauthorized",
    "message": "Invalid API key"
  }
}

Ошибки сессий и биллинга добавляют code и retryable:

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "error": {
    "type": "payment_required",
    "code": "spending_limit_exceeded",
    "message": "Spending limit exceeded",
    "retryable": false
  }
}

Коды статусов

Статус	Значение	Что делать
`400`	Плохие действие/аргументы (напр. `computer.*` на browser-only сессии)	Исправьте запрос — не повторяйте как есть
`401`	Отсутствует/неверен API-ключ или неверный `x-session-secret`	Обновите ключ; перечитайте секрет, сохранённый при создании
`402`	Превышен лимит трат или биллинг `past_due`	Поднимите лимит / закройте биллинг — см. Использование и биллинг
`429`	Сработала защита от злоупотреблений	Отступите и повторите — см. Лимиты
`5xx`	Ошибка платформы	Повторите с экспоненциальным backoff

Правила ретраев

Повторяйте: 429 и 5xx — экспоненциальный backoff с jitter, затем сдайтесь после ~3 попыток.
Не повторяйте: 400, 401, 402 (retryable: false) — сначала нужно исправить запрос или аккаунт.
Сессии: статус сессии failed терминален — уничтожьте её и создайте новую вместо бесконечного polling.
Ответы: status: insufficient_information — не ошибка — доказательств было мало. Сузьте запрос или добавьте источников вместо дословного повтора.

Чек-лист отладки

Скопируйте request_id из неудачного ответа.
Повторите с полным выводом: GET /v0/usage для состояния аккаунта, GET /v0/sessions/{id} для состояния сессии.
Проверьте Лимиты (защита, TTL) и Использование и биллинг (лимиты трат).
Найдите запрос в дашборде, затем заведите issue с request_id.

Интерактивный справочник

Спецификация OpenAPI 3.1 (генерируется из схем маршрутов, всегда синхронна) находится на api.omniscout.xyz/docs — JSON на api.omniscout.xyz/api/openapi.