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

Формат ошибок, HTTP-коды, коды ошибок по категориям, заголовки лимитов и retry-логика.

Ошибки

Формат ошибки

REST-эндпоинты возвращают ошибки в едином формате с полями code, message и необязательным hint, обёрнутыми в объект detail. Инструменты MCP используют другой формат — см. ниже.

{ "detail": { "code": "DOCUMENT_FORMAT_UNSUPPORTED", "message": "The uploaded file format is not supported.", "hint": "Supported formats: PDF, DOCX, XLSX, TXT, CSV, JSON, HTML, MD" } }

Поле	Тип	Описание
code	string	Машиночитаемый код ошибки (например, DOCUMENT_FORMAT_UNSUPPORTED)
message	string	Человекочитаемое описание ошибки
hint	string?	Необязательная подсказка для исправления ошибки

Ошибки инструментов MCP

Инструменты, вызываемые через MCP (например, connector_execute), не используют HTTP-коды. Они возвращают структурированный конверт с флагом retryable вместо hint:

{ "code": "SERVICE_RATE_LIMITED", "message": "Upstream service is rate limiting requests.", "retryable": true }

Если retryable равно true, вызов можно повторить после небольшой задержки; если false, повтор с теми же аргументами снова завершится ошибкой.

HTTP-коды ответов

Код	Описание
200	Success
201	Created — ресурс успешно создан
204	No Content — успешное удаление
400	Bad Request — неверные параметры или тело запроса
401	Unauthorized — отсутствует или недействителен токен
403	Forbidden — у токена нет нужного scope
404	Not Found — ресурс не существует
409	Conflict — ресурс уже существует (идемпотентность)
422	Unprocessable Entity — ошибка валидации
429	Too Many Requests — превышен лимит запросов
500	Internal Server Error
504	Gateway Timeout — запрос выполнялся слишком долго

Коды ошибок по категориям

Часто встречающиеся коды ошибок по категориям. Полный актуальный список доступен в интерактивном API-эксплорере.

Категория	Коды
Authentication	`AUTH_TOKEN_EXPIRED` `AUTH_TOKEN_INVALID` `AUTH_HEADER_MISSING` `AUTH_PERMISSION_DENIED` `AUTH_SCOPE_MISSING`
Documents	`DOCUMENT_FORMAT_UNSUPPORTED` `DOCUMENT_SIZE_EXCEEDED` `DOCUMENT_PASSWORD_PROTECTED` `DOCUMENT_OCR_FAILED` `DOCUMENT_NOT_FOUND`
LLM	`LLM_PROVIDER_UNAVAILABLE` `LLM_REQUEST_TIMEOUT` `LLM_PROVIDER_ERROR` `LLM_RATE_LIMITED`
Tools	`TOOL_VALIDATION_FAILED` `TOOL_NOT_FOUND` `TOOL_TIMEOUT` `TOOL_EXECUTION_FAILED`
Data	`DATA_NOT_FOUND` `DATA_CONFLICT` `DATA_INVALID_PARAMETER` `DATA_QUOTA_EXCEEDED`
Service	`SERVICE_UNAVAILABLE` `SERVICE_RATE_LIMITED` `SERVICE_CONNECTION_LOST` `SERVICE_CIRCUIT_OPEN`

Пример обработки ошибок

Рекомендуемый подход к обработке ошибок API на Python.

import requests response = requests.post(url, headers=headers, json=body) if response.status_code >= 400: error = response.json().get("detail", {}) code = error.get("code", "UNKNOWN") message = error.get("message", "An error occurred") hint = error.get("hint") if response.status_code == 429: # Rate limited — retry after delay retry_after = response.headers.get("Retry-After", "60") print(f"Rate limited. Retry after {retry_after}s") elif response.status_code == 401: # Authentication error print(f"Auth error: {message}") else: print(f"Error [{code}]: {message}") if hint: print(f"Hint: {hint}")

Лимиты запросов

Заголовки лимитов

Каждый ответ API включает заголовки с информацией о текущих лимитах.

HTTP/1.1 200 OK X-RateLimit-Limit: 60 X-RateLimit-Remaining: 58 X-RateLimit-Reset: 1711540800

Заголовок	Описание
X-RateLimit-Limit	Максимальное количество запросов в окне
X-RateLimit-Remaining	Оставшееся количество запросов
X-RateLimit-Reset	Unix-время сброса окна лимита
Retry-After	Секунды до повторной попытки (только при 429)

Лимиты по тарифам

Лимиты запросов в минуту зависят от вашего тарифного плана и общие для всей организации.

Тариф	Запросы
Free	10 req/min
Pro	30 req/min
Max	60 req/min

Сейчас применяется только лимит в минуту.

Ответ при превышении лимита

При превышении лимита API возвращает статус 429 с информацией о времени ожидания.

{ "detail": { "code": "SERVICE_RATE_LIMITED", "message": "Rate limit exceeded. Please retry after the reset time.", "hint": "Check X-RateLimit-Reset header for the reset timestamp." } }

Повторные попытки

Реализуйте экспоненциальную задержку при получении 429-ответов.

import time import requests def request_with_retry(url, headers, max_retries=3): for attempt in range(max_retries): response = requests.get(url, headers=headers) if response.status_code == 429: retry_after = int(response.headers.get("Retry-After", "60")) print(f"Rate limited. Retrying in {retry_after}s...") time.sleep(retry_after) continue return response raise Exception("Max retries exceeded")

Лучшие практики

Кэшируйте ответы, которые не меняются часто (например, список моделей)
Используйте экспоненциальную задержку при повторных попытках
Следите за заголовками X-RateLimit-Remaining для предупреждения о приближении к лимиту
Для пакетных операций используйте batch-эндпоинты вместо множественных одиночных запросов

Была ли страница полезна?