8. Коды ошибок и решение проблем
Выгрузка для ИИ (JSON)API использует HTTP-коды для синхронных ошибок и статусные поля в JSON для асинхронного жизненного цикла задач.
# 8. Коды ошибок и решение проблем
Http status codes
| Код | Статус | Описание |
|---|---|---|
| 200 | OK | Успешный синхронный ответ (например, get_result/get_spec/get_reference). |
| 202 | Accepted | create_task: задача поставлена в очередь. |
| 400 | Bad Request | Неверный JSON, отсутствует request_id или ошибка валидации обязательных полей. |
| 401 | Unauthorized | api_key отсутствует/невалиден в create_task или не передан для приватного request_id в get_result/export_result. |
| 403 | Forbidden | Передан неверный ключ для приватного request_id или нет доступа к run_worker (не localhost и нет валидного X-Worker-Token). |
| 404 | Not Found | Задача по request_id не найдена. |
| 405 | Метод не разрешен | Использован неверный HTTP-метод. |
| 409 | Conflict | export_result: задача еще не готова к экспорту. |
| 429 | Too Many Requests | Сработал rate limiter (есть заголовок Retry-After). |
| 500 | Internal Server Error | Критическая ошибка API-обработчика. |
# Внутренние ошибки задач
[CRITICAL_EXTERNAL] Ephemeris NASA data unavailable
Причина: Внешний источник эфемерид недоступен или вернул невалидные данные.
Решение: Сервис выполняет до 5 попыток с паузами. Если неуспешно — задача завершается ошибкой без частичного результата.
[CRITICAL_EXTERNAL] GeoProvider timezone unavailable
Причина: Не удалось определить таймзону/координаты через внешние geo-сервисы.
Решение: Проверьте корректность current_location/birth_city и доступность внешних API.
Portrait context is missing
Причина: Поврежденный или неполный portrait-кеш.
Решение: Пересоздайте задачу; при повторе проверьте целостность portrait-данных на сервере.
Частые вопросы
space_weather показывает simulated данные
Диагностика: Использован fallback-режим или нет наблюдаемых данных для окна расчета.
Действие: Проверяйте data_quality/meta.is_simulated. Для строгого режима используйте forecast.space_weather_mode=observed_only.
run_worker возвращает 403
Диагностика: Это ожидаемо для внешних клиентов без локального доступа/токена.
Действие: Не используйте run_worker из публичного фронта; запуск worker выполняется инфраструктурой сервера.
get_result/export_result возвращает 401 или 403
Диагностика: Задача создана приватным ключом и для чтения не передан ключ, либо передан другой ключ.
Действие: Передайте тот же API-ключ через X-API-Key или query api_key, которым создавалась задача.
Задача долго в processing
Диагностика: Ожидание внешних источников или тяжелый расчет большого периода.
Действие: Проверьте app.log/worker.log и попробуйте уменьшить состав systems или период forecast.
Экспорт возвращает 409
Диагностика: Расчет еще не завершен статусом success.
Действие: Продолжайте polling get_result до success, затем вызывайте export_result.