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, ошибка обязательных полей, structural-коды или FORECAST_INCLUDE_INVALID/FORECAST_INCLUDE_REQUIRES_FORECAST/FORECAST_TARGET_DATE_INVALID. |
| 401 | Unauthorized | api_key отсутствует/невалиден в create_task или не передан для приватного request_id в get_result/export_result/get_structural_result. |
| 403 | Forbidden | Передан неверный ключ для приватного request_id или нет доступа к run_worker (не localhost и нет валидного X-Worker-Token). |
| 404 | Not Found | Задача по request_id не найдена. |
| 405 | Метод не разрешен | Использован неверный HTTP-метод. |
| 409 | Conflict | export_result: задача ещё не готова; get_structural_result: задача создана без structural opt-in (STRUCTURAL_EXPORT_NOT_REQUESTED). |
| 422 | Unprocessable Entity | get_structural_result: задача завершена, но structural_v3 отсутствует (STRUCTURAL_EXPORT_FAILED). |
| 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-данных на сервере.
FORECAST_AGE_SEGMENT_CALCULATION_FAILED
Причина: Минимальная цепочка Matrix Destiny не смогла получить authoritative age_segment.
Решение: Результат не содержит guessed segment; проверьте birth_date и target_date либо повторите задачу.
Частые вопросы
create_task возвращает FORECAST_INCLUDE_INVALID
Диагностика: forecast.include содержит неизвестное значение или имеет неверный тип.
Действие: Передайте массив с единственным поддерживаемым selector: numerology.matrix_destiny_activation.age_segment.
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, которым создавалась задача.
get_structural_result возвращает 409
Диагностика: Исходная задача создана без response.structural_export=portrait_structural_v3.
Действие: Создайте новую задачу с structural opt-in и systems, содержащим synthesis.
get_structural_result возвращает 400 при view
Диагностика: Параметр view применим только к get_result Synthesis++.
Действие: Удалите view из запроса get_structural_result.
Задача долго в processing
Диагностика: Ожидание внешних источников или тяжелый расчет большого периода.
Действие: Проверьте app.log/worker.log и попробуйте уменьшить состав systems или период forecast.
Экспорт возвращает 409
Диагностика: Расчет еще не завершен статусом success.
Действие: Продолжайте polling get_result до success, затем вызывайте export_result.