Коды ошибок
Каждый ответ JSON с ошибкой имеет одинаковую структуру:
json
{
"error": "Job not found",
"code": "NOT_FOUND",
"requestId": "req-42"
}| Поле | Всегда присутствует | Значение |
|---|---|---|
error | Да | Понятное человеку сообщение. Его можно показывать пользователям. Не разбирайте его программно. |
code | Да | Стабильный машиночитаемый код. Ветвите логику по нему. |
requestId | Да | Идентификатор этого запроса на сервере. Указывайте его, когда сообщаете о проблеме: он совпадает с записью в журнале сервера. |
details | Иногда | Дополнительный контекст для некоторых ошибок 4xx, например сообщение о проверке. |
Сообщения могут меняться между релизами. Коды не меняются, поэтому пишите клиентскую логику на основе code.
Коды по статусу HTTP
Если маршрут не задаёт собственный код, сервер выводит его из статуса:
| Статус HTTP | code |
|---|---|
| 400 | BAD_REQUEST |
| 401 | AUTH_REQUIRED |
| 403 | FORBIDDEN |
| 404 | NOT_FOUND |
| 409 | CONFLICT |
| 413 | PAYLOAD_TOO_LARGE |
| 415 | UNSUPPORTED_MEDIA_TYPE |
| 422 | UNPROCESSABLE_ENTITY |
| 429 | RATE_LIMITED |
| 500 | INTERNAL_ERROR |
| 501 | NOT_IMPLEMENTED |
| 503 | SERVICE_UNAVAILABLE |
| 507 | INSUFFICIENT_STORAGE |
Любой другой статус 4xx получает BAD_REQUEST, а любой другой 5xx получает INTERNAL_ERROR.
Маршрут может задать более конкретный код, и тогда ответ содержит именно его. Например, инструмент, который не может запуститься из-за отсутствующего пакета ИИ, возвращает код, специфичный для функции. Эти коды описаны вместе с функцией, которая их вызывает.
Аутентификация и доступ
code | Статус | Что делать |
|---|---|---|
AUTH_REQUIRED | 401 | Передайте Authorization: Bearer <token> с токеном сессии или ключом API (si_...). |
FORBIDDEN | 403 | Учётные данные действительны, но у них нет нужного разрешения. Попросите администратора выдать разрешение. |
MUST_CHANGE_PASSWORD | 403 | Учётная запись должна сменить пароль, прежде чем вызывать другие эндпоинты. Вызовите POST /api/auth/change-password с токеном сессии, затем повторите запрос. |
USER_DISABLED | 403 | Учётная запись отключена. Администратор должен снова включить её. |
LOGIN_THROTTLED | 429 | Слишком много неудачных попыток входа. Подождите, прежде чем пробовать снова. |
VALIDATION_ERROR | 400 | Тело запроса или параметры не прошли проверку. details указывает на проблему. |
Учётная запись администратора первого запуска: admin с паролем admin, если только DEFAULT_USERNAME или DEFAULT_PASSWORD не изменили их. Если не задано SKIP_MUST_CHANGE_PASSWORD, эта учётная запись получает MUST_CHANGE_PASSWORD при каждом вызове, пока пароль не будет изменён.
Задания
Задание, завершившееся ошибкой, сообщает причину в самом задании, а не в ошибке HTTP. Прочитайте error.code и error.message из GET /api/v1/jobs/{jobId}. См. Отслеживание прогресса.
Пока не каталогизировано
Коды, которые вызываются отдельными функциями (например, шифрованием, OIDC, SCIM и командами), пока не описаны на этой странице. Каждый из них является стабильным кодом; относитесь к неперечисленному коду как к непрозрачному и обрабатывайте его по статусу.
