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

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

Ошибки

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

Все ошибки возвращаются в едином формате с полями code, message и необязательным hint.

{ "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?	Необязательная подсказка для исправления ошибки

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

Код	Описание
200	Success
201	Created — resource successfully created
204	No Content — successful deletion
400	Bad Request — invalid parameters or body
401	Unauthorized — missing or invalid token
403	Forbidden — token lacks required scope
404	Not Found — resource does not exist
409	Conflict — resource already exists (idempotency)
422	Unprocessable Entity — validation error
429	Too Many Requests — rate limit exceeded
500	Internal Server Error
504	Gateway Timeout — request took too long

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

Полный список кодов ошибок, сгруппированных по категориям.

Authentication

AUTH_TOKEN_EXPIREDAUTH_TOKEN_INVALIDAUTH_INSUFFICIENT_SCOPE

Documents

DOCUMENT_FORMAT_UNSUPPORTEDDOCUMENT_TOO_LARGEDOCUMENT_PASSWORD_PROTECTEDDOCUMENT_OCR_FAILEDDOCUMENT_EXTRACTION_FAILED

LLM

LLM_UNAVAILABLELLM_TIMEOUTLLM_ERRORLLM_RATE_LIMITED

Data

DATA_NOT_FOUNDDATA_ALREADY_EXISTSDATA_VALIDATION_ERROR

Service

SERVICE_SERVER_ERRORSERVICE_RATE_LIMITEDSERVICE_UNAVAILABLE

Network

CONNECTION_LOSTRATE_LIMITEDCIRCUIT_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	5 req/min	20 MB total
Basic	30 req/min	15 req/min	100 MB total
Pro	60 req/min	30 req/min	500 MB total
Team	120 req/min	60 req/min	2 GB total

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

При превышении лимита 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-эндпоинты вместо множественных одиночных запросов