Перейти к основному содержимому
Occult API

Подводные камни

Как API на самом деле ведёт себя там, где сгенерированный код обычно ошибается. Каждый пункт ниже описывает, как сервер обрабатывает запрос, а не вопрос стиля.

Запросы

  • Слеш в конце обязателен. /api/astro/tithi/ работает, а /api/astro/tithi отвечает 301, и клиент, который идёт по редиректу, повторяет запрос как GET без тела.
  • Одно и то же значение в разных эндпоинтах называется по-разному. Момент почти везде — date_time, но в /api/astro/chart/ и дробных картах — datetime. Смещение обычно — timezone_as_float, но кое-где — timezone, tz или time_zone. Лунный узел — rahu, node или node_type, и значения по умолчанию у них разные. Собирайте тело для каждого эндпоинта по его списку полей, а не используйте одно тело везде.
  • Долгота к западу от Гринвича отрицательная, широта к югу от экватора — тоже. Нью-Йорк — это -74.006, а не 74.006.
  • Допустимая широта у эндпоинтов разная: большинство эндпоинтов карт и панчанги принимают до ±89.9, эндпоинты прашны Аштамангала и Джамаккол — до ±66. Значение вне диапазона эндпоинта отклоняется с ошибкой 400.

Неверные данные, которые всё равно дают 200

  • date_time без смещения не считается местным временем места: большинство эндпоинтов понимают его как UTC+05:30, некоторые — как UTC. Вы получите обычный ответ 200, но для другого момента, иногда даже для предыдущего дня. Всегда передавайте смещение или Z.
  • timezone_as_float не сверяется со смещением в date_time. Если они расходятся, вы получите 200 для неверного момента. Указывайте смещение, действовавшее на ту дату (с учётом летнего времени), а не сегодняшнее; /api/astro/date_time/ вычисляет его по координатам.
  • Несколько полей при неверном значении не выдают ошибку, а подставляют запасной вариант. В /api/astro/chart/ любое значение ascendant_pos, кроме start или end, означает куспид дома, а в /api/astro/festival/ любое значение moon_option, кроме poornima, работает как amavas. Опечатка здесь меняет ответ без всякой ошибки.

Ключи

  • Если у эндпоинта есть таблица ключей, то ключ не из неё отклоняет весь запрос с ошибкой 400, и в message перечислены нераспознанные ключи. Ничего не рассчитывается и ничего не списывается.
  • Названия ключей точные и порой неожиданные: /api/astro/panchanga/ использует yogam для йоги дня, rahu_kaalam и calcualte_special_tithi (именно так, с опечаткой). Копируйте их из таблицы ключей, а не угадывайте.
  • Ключ, которому нужно дополнительное поле, без этого поля даёт ошибку 400 — например, ключ phone_number в /api/astro/numerology/ без значения phone_number.
  • Успешный вызов стоит один кредит, сколько бы ключей в нём ни было. Запрашивайте всё нужное одним вызовом — tithi, vaara, yogam и karana вместе, — а не отдельный вызов на каждый ключ.
  • У узкоспециализированных эндпоинтов вроде /api/astro/tithi/ и /api/astro/rahu-kaal/ нет таблицы ключей: они всегда возвращают один и тот же набор, а переданный им массив keys не используется.
  • В /api/astro/numerology/ допустимые ключи зависят от system. Ключ из набора другой системы вернёт 400 с его названием.

Кредиты, ошибки и лимиты

  • Большинство эндпоинтов стоят один кредит за успешный вызов. /api/astro/chat/, /api/astro/pdf/horoscope/ и /api/astro/pdf/yearbook/ стоят по 25 — не вызывайте их в циклах и при повторных попытках.
  • Неудачные вызовы бесплатны: кредиты резервируются до начала расчёта и возвращаются при любом ответе не из диапазона 2xx — в таком ответе стоит X-Credits-Charged: 0.
  • Платные ответы содержат X-Credits-Cost, X-Credits-Charged и X-Credits-Remaining, а также поминутные X-RateLimit-Limit и X-RateLimit-Remaining. Читайте их, а не считайте баланс сами.
  • Когда кредиты закончились, приходит 402 с message insufficient_credits; в его data есть cost_credits, credits_remaining и recharge_url. Повторять запрос бесполезно, пока тариф не повышен или квота не обновилась.
  • При превышении поминутного лимита приходит 429 с message api_key_rate_limited и заголовком Retry-After (то же значение — в retry_after_seconds внутри data). Подождите это время, прежде чем повторять запрос.
  • Искажённый, отозванный или просроченный ключ возвращает 401 invalid_api_key. Маршрут, право доступа (scope) или IP-адрес, которые вашему ключу запрещены, дают 403 endpoint_not_allowed, scope_not_allowed или ip_not_allowed.
  • Ошибки проверки ключа и кредитов выглядят как { "error": "…", "message": "insufficient_credits", "is_error": true, "data": { … } }: опирайтесь на код в message. Ответы расчётов при неудаче приходят в формате { "data": {}, "status": 400, "is_error": true, "message": "…" }, а причина описана текстом в message. В обоих случаях есть is_error.
  • Два PDF-эндпоинта возвращают сам PDF (application/pdf), а не JSON. Запишите тело ответа в файл — ссылки для скачивания потом не будет.

Астрология

  • Ведические эндпоинты работают в сидерическом зодиаке и сами делают поправку на аянамшу на сервере; маршруты /api/astro/western/ по умолчанию тропические. Не вычитайте аянамшу из результата сами.
  • /api/astro/kp-chart/ использует куспиды Плацидуса в сидерическом зодиаке, поэтому для того же рождения положения по домам могут отличаться от /api/astro/chart/. Это метод KP, а не несогласованность.
  • Рашифал — прогноз по знаку, без натальной карты: передавайте rashi английским названием знака, например leo, а не данные рождения.
  • Карты таро вытягиваются случайно, если не передать seed. Каждый ответ возвращает использованный seed — сохраните его, если расклад нужно будет показать снова точно таким же.
  • /api/astro/numerology/iching/ численно сопоставляет дату и имя с одной из 64 гексаграмм. Гадания нет, поэтому нет ни изменяющихся черт, ни второй гексаграммы.

Дальше

Форматы полейТочные форматы запросовЧто умеет APIЧто умеет API и где его границы