Ir al contenido
Occult API

Trampas habituales

Cómo se comporta de verdad la API justo donde el código generado suele fallar. Cada punto describe cómo trata el servidor la solicitud; no son preferencias de estilo.

Solicitudes

  • La barra final es obligatoria. /api/astro/tithi/ funciona; /api/astro/tithi responde con un 301, y el cliente que sigue la redirección la reenvía como GET, sin el cuerpo.
  • El mismo valor tiene nombres de campo distintos según el endpoint. El momento es date_time en casi todos, pero datetime en /api/astro/chart/ y en las cartas divisionales. La diferencia horaria suele ser timezone_as_float, pero en algunos es timezone, tz o time_zone. El nodo lunar es rahu, node o node_type, y cada uno tiene su valor por defecto. Arma cada cuerpo con la lista de campos de su endpoint, en vez de reutilizar el mismo cuerpo en todas partes.
  • La longitud es negativa al oeste de Greenwich, y la latitud, negativa al sur del ecuador. Nueva York es -74.006, no 74.006.
  • Los límites de latitud no son iguales en todos: la mayoría de los endpoints de cartas y panchang aceptan hasta ±89.9, y los de Prashna Ashtamangala y Jamakkol, hasta ±66. Un valor fuera del rango del endpoint se rechaza con un 400.

Datos incorrectos que aun así devuelven 200

  • Un date_time sin diferencia horaria no se toma como hora local del lugar: casi todos los endpoints lo leen como UTC+05:30, y unos pocos como UTC. Recibes un 200 normal, pero para otro momento, a veces del día anterior. Envía siempre la diferencia horaria o una Z.
  • Nadie comprueba que timezone_as_float coincida con la diferencia horaria de date_time. Si no coinciden, recibes un 200 para el momento equivocado. Usa la diferencia que regía en esa fecha (horario de verano incluido), no la de hoy; /api/astro/date_time/ la calcula a partir de las coordenadas.
  • Algunos campos, en vez de fallar, toman un valor alternativo: en /api/astro/chart/, cualquier ascendant_pos que no sea start o end se interpreta como la cúspide de la casa, y en /api/astro/festival/, cualquier moon_option que no sea poornima funciona como amavas. Una errata ahí cambia el resultado sin dar error.

Claves (keys)

  • En un endpoint con tabla de claves, cualquier clave que no esté en ella hace que se rechace toda la solicitud con un 400, y el mensaje indica qué claves no se reconocen. No se calcula nada ni se cobra nada.
  • Los nombres de las claves son exactos y a veces sorprenden: /api/astro/panchanga/ usa yogam para el yoga del día, rahu_kaalam y calcualte_special_tithi (escrito así). Cópialos de la tabla de claves en lugar de adivinarlos.
  • Una clave que necesita un campo adicional da un 400 si ese campo falta; por ejemplo, la clave phone_number de /api/astro/numerology/ sin un valor phone_number.
  • Cada llamada correcta cuesta un crédito, da igual cuántas claves pida. Pide todo lo que necesites en una sola llamada (tithi, vaara, yogam y karana juntas) en vez de hacer una llamada por clave.
  • Los endpoints con una única función, como /api/astro/tithi/ y /api/astro/rahu-kaal/, no tienen tabla de claves: siempre devuelven el mismo conjunto de datos, y si les envías un array keys, se ignora.
  • En /api/astro/numerology/, las claves válidas dependen de system. Una clave de otro sistema devuelve un 400 que la menciona.

Créditos, errores y límites

  • La mayoría de los endpoints cuestan un crédito por llamada correcta. /api/astro/chat/, /api/astro/pdf/horoscope/ y /api/astro/pdf/yearbook/ cuestan 25 cada uno: no los metas en bucles ni en reintentos.
  • Las llamadas fallidas no se cobran: los créditos se reservan antes del cálculo y se devuelven ante cualquier respuesta que no sea 2xx, que entonces trae X-Credits-Charged: 0.
  • Las respuestas que consumen créditos traen X-Credits-Cost, X-Credits-Charged y X-Credits-Remaining, además de X-RateLimit-Limit y X-RateLimit-Remaining, que van por minuto. Léelas en vez de llevar tú la cuenta del saldo.
  • Sin créditos, recibes un 402 con message insufficient_credits; su data trae cost_credits, credits_remaining y recharge_url. Reintentar no sirve hasta que mejores el plan o se reinicie su cuota.
  • Si superas el límite por minuto, recibes un 429 con message api_key_rate_limited y la cabecera Retry-After (también retry_after_seconds en data). Espera ese tiempo antes de reintentar.
  • Una clave mal formada, revocada o caducada devuelve 401 invalid_api_key. Una ruta, un scope o una dirección IP que tu clave no puede usar devuelve 403 endpoint_not_allowed, scope_not_allowed o ip_not_allowed.
  • Los errores de las comprobaciones de clave y créditos tienen esta forma: { "error": "…", "message": "insufficient_credits", "is_error": true, "data": { … } }. Decide según el código de message. Cuando falla un cálculo, la respuesta usa la estructura { "data": {}, "status": 400, "is_error": true, "message": "…" }, con el motivo en texto en message. Las dos llevan is_error.
  • Los dos endpoints de PDF devuelven el PDF en sí (application/pdf), no JSON. Guarda el cuerpo en un archivo; no hay ningún enlace de descarga que pedir después.

Astrología

  • Los endpoints védicos son siderales y aplican la corrección del ayanamsa en el servidor; las rutas /api/astro/western/ son tropicales por defecto. No restes tú ningún ayanamsa al resultado.
  • /api/astro/kp-chart/ usa cúspides Placidus sobre el zodíaco sideral, así que, para el mismo nacimiento, las casas pueden no coincidir con las de /api/astro/chart/. Es el método KP, no una incoherencia.
  • El rashifal es una previsión por signo, sin carta natal: envía rashi con el nombre del signo en inglés, como leo, no datos de nacimiento.
  • Las tiradas de tarot son aleatorias salvo que envíes seed. Cada respuesta devuelve la semilla que usó; guárdala si necesitas mostrar otra vez la misma lectura.
  • /api/astro/numerology/iching/ asocia numéricamente una fecha y un nombre a uno de los 64 hexagramas. No hay tirada, así que no hay líneas mutables ni segundo hexagrama.

Siguiente

Formato de los camposLos formatos exactos de las solicitudesCobertura y alcanceQué cubre la API y dónde termina