Перейти до вмісту
Occult API

Підводні камені

Як API насправді поводиться там, де згенерований код зазвичай помиляється. Кожен пункт нижче — це те, як сервер обробляє запит, а не питання стилю.

Запити

  • Слеш у кінці обов’язковий. /api/astro/tithi/ працює, а /api/astro/tithi відповідає 301 — і клієнт, який іде за редиректом, надсилає запит повторно як GET без тіла.
  • Те саме значення в різних ендпоінтах називається по-різному. Момент майже скрізь — date_time, але datetime на /api/astro/chart/ і в дробових картах; зміщення зазвичай — 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, а в повідомленні названо нерозпізнані ключі. Нічого не рахується й нічого не списується.
  • Назви ключів точні, а часом і несподівані: /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 (а в data — ще й retry_after_seconds). Зачекайте стільки, перш ніж повторювати.
  • Хибний, відкликаний або прострочений ключ повертає 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 і де його межі