Perguntas frequentes

Quanto custa uma chamada?

Um crédito por chamada bem-sucedida, não importa o tamanho da resposta. As exceções são os endpoints de relatório em PDF e de chat com IA, que custam 25 créditos por chamada. Pedir um cálculo ou quarenta custa o mesmo, porque muitos endpoints aceitam um array `keys`, e todas as chaves de uma requisição entram nesse único crédito.

Requisições que falham são cobradas?

Não. A Occult API nunca cobra por requisição que falha. O crédito é reservado antes do cálculo e devolvido se ele não terminar sem erro. Assim, um 4xx, um 5xx ou um timeout não custam nada, e uma integração com bug não consegue esvaziar o saldo enquanto você depura. Toda resposta informa o custo real no cabeçalho X-Credits-Charged.

Os créditos vencem?

A cota de um plano recomeça todo mês. A Occult API é vendida em planos mensais ou anuais: cada mês traz uma cota nova, e as chamadas que você não usou em um mês não passam para o seguinte. Os planos anuais funcionam do mesmo jeito: doze cotas mensais, cobradas de uma só vez.

Tem plano grátis?

Contas novas ganham créditos grátis para usar na API real com uma chave real, e não em um sandbox com dados à parte. Além disso, o Playground em occultapi.com/playground faz chamadas de verdade à API em funcionamento usando a sua chave, e uma chamada que falha ali não custa nada.

Tem assinatura?

Sim. A Occult API é vendida em planos mensais ou anuais, que se renovam automaticamente até você cancelar. O cancelamento interrompe a próxima renovação, e o período atual continua valendo até terminar. Nenhum nível esconde endpoints: todo plano pode chamar todos eles.

Estou recebendo 402. Minha chave está errada?

Não. Um 402 com a mensagem insufficient_credits quer dizer que a chave de API é válida e a cota acabou. Gerar outra chave não resolve: mude para um plano maior ou aguarde a cota recomeçar no próximo mês. Só o 401 invalid_api_key indica problema na chave.

Posso usar a chave de API no navegador ou em um app mobile?

Não. A chave da Occult API é um segredo que fica no servidor. Se ela estiver no JavaScript do front-end ou no pacote de um app mobile, qualquer pessoa que instalar o app ou abrir as ferramentas de desenvolvedor consegue ler a chave e gastar o seu saldo. Chame a API do seu servidor e ofereça ao cliente um endpoint seu.

Perdi minha chave. Vocês podem mandar de novo?

Não, e é de propósito. A Occult API guarda as chaves só como hash SHA-256, então nem um administrador nem um dump do banco de dados consegue recuperá-las. Crie uma chave nova e revogue a antiga: isso vale na hora e não mexe no saldo de créditos.

E se uma chave vazar?

Revogue a chave na página de chaves; a revogação é imediata. Toda chave tem um prefixo público de oito caracteres, indexado justamente para que uma chave vazada em um repositório público possa ser encontrada e revogada só pelo prefixo, sem que ninguém precise da parte secreta.

De onde vêm os cálculos?

A Occult API calcula a partir das efemérides da NASA JPL, com o conjunto completo de dados, 735 estrelas fixas e cobertura de 500 a 2999 d.C. Nada sai de uma tabela de almanaque pronta: cada resposta é calculada para o instante e as coordenadas exatos da requisição.

O resultado de vocês não bate com outra fonte. Por quê?

Quase sempre o motivo é o ayanamsa. As tradições indianas realmente discordam sobre ele, e uma diferença de um grau pode jogar um planeta para o outro lado do limite de um nakshatra. A Occult API oferece 48 ayanamsas, e cada um pode ser corrigido em graus, minutos e segundos. Então, a primeira coisa a conferir é se as duas fontes usam o mesmo.

Qual é a velocidade?

O tempo mediano de resposta no servidor é de 62 ms, medido em todos os exemplos publicados, e não em um escolhido a dedo. Alguns poucos endpoints fazem varreduras pesadas, como um varshaphal completo ou um ano de raasi dasha, e levam segundos. A referência diz isso claramente, em vez de esconder esses casos atrás da mediana.

Tem especificação OpenAPI ou SDK?

A Occult API publica um documento OpenAPI 3.1 em occultapi.com/openapi.json, gerado do mesmo catálogo da documentação, com um exemplo em cada operação: 255 dos 299 foram capturados de um servidor real, e o resto deriva do schema da requisição. Com o openapi-generator ou qualquer ferramenta parecida, você gera um cliente tipado na linguagem que quiser. Também há uma coleção do Postman e um servidor MCP para assistentes de IA.

Um assistente de IA consegue chamar a API?

Sim. A Occult API publica um servidor MCP que dá acesso a todos os endpoints por meio de cinco ferramentas. Buscar endpoints e ler schemas de requisição por ele não consome créditos, só um cálculo de verdade consome. Assim, o assistente pode explorar a API inteira antes de gastar qualquer coisa. Há um guia para agentes de código em occultapi.com/AGENTS.md.

Posso vender o que a API retorna?

Sim. A Occult API concede uma licença isenta de royalties para usar os dados comercialmente nos seus produtos, o que inclui guardar respostas no seu banco de dados, gerar e vender relatórios e usar os dados em trabalhos para clientes. Não é preciso dar crédito. O que não é permitido é revender o próprio acesso à API como uma API.

Vocês guardam os dados de nascimento que eu envio?

Não. A data, a hora e o local da requisição servem para calcular a resposta e não são gravados em banco de dados depois. De cada chamada, guardamos o endpoint, o timestamp, o status HTTP e os créditos consumidos, que é o necessário para relatórios de uso e dúvidas de cobrança.

Vocês oferecem DPA?

Sim. A Occult API publica um Acordo de Tratamento de Dados (DPA) que atende ao Artigo 28 do GDPR, e uma lista atualizada de suboperadores com todos os terceiros que podem acessar dados de clientes.

Se a sua pergunta não está aqui, escreva para mridul.kabra23@gmail.com. O que medimos e o que não medimos está em metodologia; o que guardamos e o que não construímos, em transparência. Todos os códigos de erro estão em autenticação, inclusive o motivo de 402 não ser falha de autenticação.