Ошибки Roo Code при работе с API: 401, 404, 429 и таймауты (2026)

При подключении стороннего API к Roo Code большинство ошибок связано не с возможностями модели, а с выбором Provider, Base URL, ключом, ограничениями скорости или сетью: только настроили — 401, сменили адрес — 404, длинная задача дошла до половины — 429, поток завис до таймаута. Порядок действий: сначала статус-код и тип ошибки, затем request-id, и только потом правки промпта. Ниже разобраны 401, 404, 429, переполнение контекста и таймауты, с шагами диагностики, списком логов и примером кода. Модели и тарификация — по тарифам на модели.

1. Сначала уровни: где именно возникает ошибка

Запрос проходит через клиент Roo Code, хост расширения VS Code, сеть и прокси, шлюз и вышестоящую модель. Один и тот же 401 может означать неверный ключ или несовпадение протокола Provider; один и тот же 404 — лишний /v1 в пути или отсутствующий ID модели. Сначала определите уровень, чтобы не менять конфигурацию в неверном направлении.

Статус	Тип ошибки	Частая причина	Что делать
400	invalid_request_error	Параметры, длина контекста или лимит расходов	Исправить запрос или лимит и повторить
401	authentication_error	Ключ отсутствует, неверен, истёк, несовпадение заголовка авторизации	Исправить учётные данные, не повторять
402	billing_error	Проблема с балансом или счётом	Проверить счёт
403	permission_error	У ключа нет прав на модель или проект	Проверить авторизацию
404	not_found_error	Неверный путь или ID модели	Проверить Base URL и имя модели
413	request_too_large	Тело запроса превышает лимит	Сжать или разбить запрос
429	rate_limit_error	Частота, параллельность или лимит расходов	Повторить с задержкой
500	api_error	Внутренняя ошибка сервера	Повторить с задержкой
504	timeout_error	Превышено время обработки	Перейти на потоковый режим или разбить запрос

request-id из заголовков или тела ошибки нужно сохранять. В логах фиксируйте минимум время, статус, тип ошибки, ID модели и ID запроса; не записывайте полный ключ и чувствительный код.

2. 401: Provider, ключ и заголовок авторизации

В Roo Code выпадающий список Provider и поле ключа разделены. Самый частый 401 — не недействительный ключ, а неверная комбинация: ключ OpenAI-совместимого шлюза вставлен в Provider Anthropic или наоборот; Base URL указывает на среду A, а ключ принадлежит среде B; после переключения профиля остался старый ключ.

Другие причины: пробелы, переводы строк, кавычки или полноширинные символы вокруг ключа; ключ удалён, истёк или принадлежит другой рабочей области; корпоративный прокси переписывает или удаляет заголовок Authorization; в одном расширении одновременно настроены вход по подписке и API-ключ.

Порядок проверки:

Убедитесь, что тип Provider соответствует протоколу Base URL: OpenAI-совместимый — /v1/chat/completions, Anthropic — /v1/messages.
С тем же ключом и Base URL отправьте из терминала один минимальный запрос.
Если прямой запрос успешен, а Roo Code падает — проблема в настройках Provider, профиле или прокси; если и прямой запрос не проходит — в ключе, шлюзе или сети.
Проверьте с новым ключом, чтобы исключить ошибку копирования.

401 не повторяйте: повторы только раздувают логи и оповещения.

3. 404: путь Base URL и ID модели

404 бывает двух видов: путь не существует или модель не существует.

Проблема пути: у OpenAI-совместимого Provider Base URL обычно указывают до /v1, а /chat/completions клиент добавляет сам. Если вписать полный /v1/chat/completions, путь может продублироваться. Завершающий слэш, двойные слэши, регистр и лишние пробелы тоже дают 404. Provider Anthropic добавляет /v1/messages, поэтому OpenAI-совместимый адрес в нём также приведёт к 404.

Проблема модели: если в сообщении есть model not found, invalid model или The model does not exist, скопируйте точный ID из списка моделей шлюза или со страницы тарифов. Псевдонимы, суффиксы даты и регистр могут отличаться; некоторые шлюзы требуют префикс поставщика. Проверьте также права ключа на эту модель: при недостатке прав иногда возвращается 403, иногда 404.

Быстрая проверка: вызовите /v1/models, посмотрите доступные ключу модели и отправьте минимальный запрос с ID из списка.

4. 429: ограничения, квоты и шторм повторов

429 означает, что запрос превысил лимит частоты, параллельности или расходов. Частые причины:

превышено число запросов или токенов в минуту;
несколько инструментов или сотрудников используют один ключ;
подзадачи Orchestrator или параллельные вызовы инструментов в Roo Code поднимают мгновенную параллельность;
повторы идут без задержки и превращаются в шторм;
сработал лимит баланса или расходов рабочей области.

Сначала смотрите заголовок retry-after: если он есть, ждите указанное время; если нет — используйте экспоненциальную задержку со случайным разбросом и ограничьте число попыток. Часть 429 по квоте не содержит retry-after, и ожидание не поможет — нужно пополнить баланс или изменить лимит.

Учитывайте наложение двух уровней повторов: Roo Code может повторять сам, SDK или шлюз тоже повторяют, а бизнес-логика добавляет третий уровень — фактическое число запросов умножается. Планируйте повторы клиента, SDK и приложения совместно. Для 401, 403, 404 и 400 повторы не нужны.

5. 400 и 413: длина контекста и тело запроса

Переполнение контекста обычно возвращает 400 с текстом вроде context length, maximum context, prompt is too long. Причина не в поломке модели, а в том, что бюджет «вход + выход» превышает окно.

В Roo Code отдельно следите за настройкой контекстного окна: если вручную указать значение больше реальной поддержки модели, клиент будет обрезать контекст по неверному бюджету или отправлять слишком длинный запрос — результат 400. Приведите окно к значению из документации модели и включите сжатие контекста или condensing, если текущая версия это поддерживает.

Порядок действий:

Сократите число одновременно читаемых файлов, передавайте только релевантные фрагменты.
Сжимайте вывод терминала и ответы MCP-инструментов, оставляя необходимые поля.
Длинные документы делите по главам и обрабатывайте частями.
Очищайте раннюю историю, оставляя system, последние реплики и краткое резюме.
Оставляйте место для выхода: max_tokens ограничивает только выход и не решает проблему входа.

413 request_too_large — слишком большое тело запроса, это не то же самое, что длина контекста. Чаще всего срабатывают скриншоты, PDF и base64-изображения; сжимайте изображения, сокращайте вложения или делите запрос.

6. Таймауты и обрывы потока: стриминг, прокси и длинные задачи

Roo Code по умолчанию использует потоковый вывод. Потоковый запрос может сначала вернуть HTTP 200, а затем отправить событие ошибки внутри SSE. Клиент, который смотрит только на статус, примет сбой за успех. Нужно разбирать события ошибок в потоке и убеждаться, что получен корректный маркер завершения; иначе результат следует помечать как неполный.

Типичные источники таймаутов:

корпоративный прокси, VPN или TLS-инспекция делают соединение нестабильным;
проблемы DNS, IPv6, firewall или MTU;
слишком длинный одиночный запрос, и простаивающее соединение разрывается;
длинная задача агента непрерывно вызывает инструменты, и суммарное время превышает лимит клиента или шлюза;
вышестоящая модель стоит в очереди, первый байт приходит очень медленно.

На практике сначала используйте потоковый режим; задайте разумный таймаут на запрос; делите длинные задачи на этапы; сократите набор инструментов с автоодобрением; проверьте другую сеть или мобильную точку доступа, чтобы понять, локальная ли это проблема. При корпоративной TLS-инспекции нужно, чтобы VS Code и система доверяли соответствующему CA; клиентам на Node иногда требуется NODE_EXTRA_CA_CERTS.

7. Логи и поддержка: как описать проблему

Не ограничивайтесь сообщением «выдаёт ошибку». Соберите информацию по списку:

Время, часовой пояс, длительность.
Версия Roo Code, VS Code и операционной системы.
Тип Provider, Base URL (только домен), ID модели.
Был ли потоковый режим, время запроса, число повторов.
HTTP-статус, тип ошибки и полный текст.
request-id — он может быть и в заголовках, и в теле ответа.
Масштаб: одна машина, один проект, одна сеть или вся команда.
Минимальное воспроизведение: один curl или минимальный репозиторий и результат того же запроса к официальному входу.

Где искать логи: в VS Code откройте панель Output и найдите канал, связанный с Roo Code; ошибки хоста расширения и MCP-инструментов могут быть в консоли Developer Tools; по проблемам шлюза передайте request-id в поддержку шлюза. После архивации основного репозитория GitHub issues могут быть доступны только для чтения — сначала уточните канал поддержки используемого форка. Обезличивайте логи конкретно: в ключе оставляйте первые и последние четыре символа, промпты и код обрабатывайте по корпоративным правилам.

8. Пример: повторять или нет по типу ошибки

Ниже пример на OpenAI-совместимом интерфейсе: 401 и 404 завершаются сразу, 429, 5xx и таймаут повторяются с задержкой. Скрипт можно использовать для воспроизведения или встроить в пакетную обработку.

import os
import random
import time

from openai import (
    APIConnectionError,
    APIStatusError,
    APITimeoutError,
    AuthenticationError,
    NotFoundError,
    OpenAI,
    RateLimitError,
)

client = OpenAI(
    base_url=os.environ["OPENAI_BASE_URL"],
    api_key=os.environ["OPENAI_API_KEY"],
)

def ask(prompt: str, retries: int = 4) -> str:
    for attempt in range(retries):
        try:
            resp = client.chat.completions.create(
                model=os.environ["OPENAI_MODEL"],
                messages=[{"role": "user", "content": prompt}],
                timeout=120,
            )
            return resp.choices[0].message.content or ""
        except AuthenticationError as exc:
            raise SystemExit(f"401: проверьте Provider, ключ и заголовок авторизации, request-id={exc.request_id}") from exc
        except NotFoundError as exc:
            raise SystemExit(f"404: проверьте Base URL и ID модели, request-id={exc.request_id}") from exc
        except RateLimitError:
            wait = min(2 ** attempt, 20) + random.random()
            print(f"429: повтор через {wait:.1f} с")
            time.sleep(wait)
        except (APITimeoutError, APIConnectionError):
            wait = min(2 ** attempt, 10) + random.random()
            print(f"Таймаут или сбой соединения: повтор через {wait:.1f} с")
            time.sleep(wait)
        except APIStatusError as exc:
            if exc.status_code >= 500:
                wait = min(2 ** attempt, 20) + random.random()
                print(f"{exc.status_code}: повтор через {wait:.1f} с")
                time.sleep(wait)
                continue
            raise

    raise RuntimeError("Попытки исчерпаны, переходите к деградации или оповещению")

print(ask("Ответь только OK"))

В примере явно не задано число повторов SDK; в продакшене настраивайте повторы SDK и бизнес-логики вместе. Base URL обычно указывают как https://ai.zhongshangqihang.com/v1, ID модели копируют из тарифов на модели.

Частые вопросы

401 всегда означает неверный ключ?

Нет. Несовпадение типа Provider, Base URL, указывающий на другую среду, и прокси, переписывающий заголовок авторизации, тоже дают 401. Сначала проверьте тот же ключ и Base URL прямым запросом, затем настройки Provider и профиля в Roo Code.

При 404 с model not found как подтвердить ID модели?

Вызовите /v1/models, получите список, доступный текущему ключу, и скопируйте точный ID — не пишите по памяти. Затем проверьте, не дублируется ли путь в Base URL и совпадает ли протокол Provider.

После 429 достаточно подождать?

Не всегда. Ограничение скорости обычно проходит; 429 по квоте или балансу может не содержать retry-after, и ожидание не поможет — нужен новый лимит или пополнение. Сначала смотрите тип ошибки и заголовки.

Переполнение контекста — проблема модели?

Обычно нет. Это превышение бюджета «вход + выход» над окном либо слишком большое контекстное окно в настройках Roo Code. Сократить вход, включить сжатие и разбить задачу — обычно быстрее, чем менять модель.

Потоковый запрос вернул 200 и оборвался — это успех?

Нет. После 200 поток может отправить событие ошибки через SSE. Клиент должен разобрать поток и подтвердить корректное завершение, иначе результат помечается как неполный с повтором или оповещением.

Что дальше

Создайте тестовый ключ в ZSQH AI Gateway, прогоните curl и скрипт из статьи для 401, 404, 429 и таймаута, затем подключайте продакшн-мониторинг. Доступность моделей и тарификация — по тарифам на модели.