Pegadinhas do domínio

Como a API se comporta de verdade nos pontos onde o código gerado costuma errar. Cada item mostra como o servidor trata a requisição — não é questão de estilo.

Requisições

A barra final é obrigatória. /api/astro/tithi/ funciona; /api/astro/tithi responde 301, e o cliente que segue o redirecionamento reenvia a requisição como GET, sem o corpo.
O mesmo valor tem nomes de campo diferentes em endpoints diferentes. O momento é date_time em quase todos, mas datetime em /api/astro/chart/ e nos mapas divisionais; o offset costuma ser timezone_as_float, mas em alguns é timezone, tz ou time_zone; o nodo lunar é rahu, node ou node_type, cada um com seu padrão. Monte cada corpo a partir da lista de campos do endpoint, em vez de reaproveitar o mesmo corpo em todo lugar.
A longitude é negativa a oeste de Greenwich, e a latitude, negativa ao sul do equador. Nova York é -74.006, não 74.006.
Os limites de latitude variam: a maioria dos endpoints de mapa e de panchang aceita até ±89.9; os de Prashna Ashtamangala e Jamakkol, até ±66. Um valor fora da faixa do endpoint é rejeitado com 400.

Entradas erradas que mesmo assim retornam 200

Um date_time sem offset não é lido como a hora local do lugar: a maioria dos endpoints o trata como UTC+05:30, e alguns como UTC. A resposta é um 200 normal, mas para outro momento — às vezes o dia anterior. Envie sempre um offset ou Z.
A API não confere timezone_as_float com o offset de date_time. Se os dois não baterem, você recebe um 200 para o momento errado. Use o offset vigente naquela data (horário de verão incluído), não o de hoje; /api/astro/date_time/ descobre o offset a partir das coordenadas.
Alguns campos assumem um valor padrão em vez de falhar: em /api/astro/chart/, qualquer ascendant_pos diferente de start ou end vira a cúspide da casa; em /api/astro/festival/, qualquer moon_option diferente de poornima é tratado como amavas. Um erro de digitação ali muda a resposta sem gerar erro.

Chaves (keys)

Num endpoint com tabela de chaves, qualquer chave fora dela faz a requisição inteira ser rejeitada com 400, e a mensagem cita as chaves não reconhecidas. Nada é calculado, nada é cobrado.
Os nomes das chaves são exatos e às vezes surpreendem: /api/astro/panchanga/ usa yogam para o yoga do dia, rahu_kaalam e calcualte_special_tithi (escrito assim mesmo). Copie da tabela de chaves em vez de adivinhar.
Uma chave que exige um campo extra falha com 400 se o campo faltar — por exemplo, a chave phone_number de /api/astro/numerology/ sem um valor em phone_number.
Uma chamada bem-sucedida custa um crédito, não importa quantas chaves ela peça. Peça tudo de uma vez — tithi, vaara, yogam e karana juntas — em vez de fazer uma chamada por chave.
Endpoints de uso único, como /api/astro/tithi/ e /api/astro/rahu-kaal/, não têm tabela de chaves: sempre devolvem o mesmo conjunto fixo, e um array keys enviado a eles é ignorado.
Em /api/astro/numerology/, as chaves válidas dependem de system. Uma chave do conjunto de outro sistema retorna 400, e a mensagem diz qual é.

Créditos, erros e limites

A maioria dos endpoints custa um crédito por chamada bem-sucedida. /api/astro/chat/, /api/astro/pdf/horoscope/ e /api/astro/pdf/yearbook/ custam 25 cada — deixe esses fora de loops e de novas tentativas automáticas.
Chamada que falha não custa nada: os créditos são reservados antes do cálculo e devolvidos em qualquer resposta fora da faixa 2xx, que então traz X-Credits-Charged: 0.
As respostas cobradas trazem X-Credits-Cost, X-Credits-Charged e X-Credits-Remaining, além de X-RateLimit-Limit e X-RateLimit-Remaining, por minuto. Leia esses cabeçalhos em vez de controlar o saldo por conta própria.
Sem créditos, a resposta é 402 com message insufficient_credits; o data traz cost_credits, credits_remaining e recharge_url. Tentar de novo não adianta até você mudar para um plano maior ou a cota recomeçar.
Passou do limite por minuto, a resposta é 429 com message api_key_rate_limited e o cabeçalho Retry-After (também retry_after_seconds em data). Espere esse tempo antes de tentar de novo.
Uma chave mal formada, revogada ou expirada retorna 401 invalid_api_key. Uma rota, um escopo ou um endereço IP que sua chave não pode usar retorna 403 endpoint_not_allowed, scope_not_allowed ou ip_not_allowed.
Os erros da verificação de chave e de créditos têm o formato { "error": "…", "message": "insufficient_credits", "is_error": true, "data": { … } }: decida pelo código em message. Quando um cálculo falha, a resposta usa o envelope { "data": {}, "status": 400, "is_error": true, "message": "…" }, com o motivo por extenso em message. Os dois trazem is_error.
Os dois endpoints de PDF devolvem o próprio PDF (application/pdf), não JSON. Grave o corpo num arquivo; não existe link de download para buscar depois.

Astrologia

Os endpoints védicos são siderais e fazem a correção do ayanamsa no servidor; as rotas /api/astro/western/ são tropicais por padrão. Não subtraia você mesmo um ayanamsa do resultado.
/api/astro/kp-chart/ usa cúspides Placidus no zodíaco sideral, então as casas podem sair diferentes das de /api/astro/chart/ para o mesmo nascimento. Isso é o método KP, não uma inconsistência.
O rashifal é uma previsão por signo, sem mapa natal: envie rashi com o nome do signo em inglês, como leo, e não dados de nascimento.
As tiragens de tarô são aleatórias, a não ser que você envie seed. Toda resposta devolve a seed usada; guarde-a se precisar mostrar a mesma leitura de novo, idêntica.
/api/astro/numerology/iching/ associa uma data e um nome aos 64 hexagramas de forma numérica. Nada é lançado, então não há linhas mutáveis nem segundo hexagrama.

Próximos passos

Formatos dos camposOs formatos exatos de requisição Cobertura e escopoO que a API cobre e até onde vai