Autenticação
Um cabeçalho, uma chave e poucos erros — cada um com um significado preciso.
O cabeçalho
Envie sua chave em X-API-Key em toda requisição. Não tem fluxo OAuth, nem troca de token, nem nada para renovar.
curl -X POST https://api.occultapi.com/api/astro/tithi/ \
-H "X-API-Key: yt_live_a1b2c3d4_x9K2mQ7vB4nR8sL1wY6tZ3pC5hJ0dF" \
-H "Content-Type: application/json" \
-d '{ "date_time": "2026-09-16T06:00:00+05:30", "latitude": 26.9124, "longitude": 75.7873, "timezone_as_float": 5.5 }'Formato da chave
As chaves têm este formato: yt_live_a1b2c3d4_x9K2mQ7vB4nR8sL1wY6tZ3pC5hJ0dF — marca, ambiente, um prefixo público de oito caracteres e, por fim, o segredo.
yt_live_…gasta créditos de verdade do seu saldo.yt_test_…é para desenvolvimento e aparece marcada assim nos seus registros de uso.
O prefixo é público e indexado de propósito: se uma chave vazar num repositório público, dá para encontrá-la e revogá-la só pelo prefixo, sem que ninguém precise da parte secreta.
Exibida uma vez, guardada como hash
A chave aparece uma única vez, quando você a cria. Guardamos só um hash SHA-256, então nem um administrador nem um dump do banco de dados conseguem recuperá-la — e, por isso mesmo, não temos como enviá-la de novo para você. Depois disso, você vê apenas o prefixo e os quatro últimos caracteres, o bastante para distinguir duas chaves numa lista.
Perdeu a chave? Crie uma nova e revogue a antiga. É mais rápido do que falar com a gente — e é tudo o que poderíamos fazer, de qualquer jeito.
Erros — e quais não são de autenticação
Todo erro usa o envelope padrão, com is_error: true e um código estável, legível por máquina, em message. Decida pelo código, não pelo texto.
| Status | message | O que significa | O que fazer |
|---|---|---|---|
| 401 | invalid_api_key | A chave está ausente, mal formada, revogada ou expirada. | Confira se o cabeçalho X-API-Key está mesmo chegando até nós. Se você trocou a chave, faça o deploy da nova. |
| 402 | insufficient_credits | A chave é válida. O saldo é que está zerado. | Mude para um plano maior ou aguarde a cota recomeçar no próximo mês. Não é problema de autenticação — gerar outra chave não adianta. |
| 403 | endpoint_not_allowed | Essa rota não está disponível para chaves de API: o caminho ou o método está errado, ou o endpoint foi descontinuado. | Compare a rota e o método com a referência. Nem tentar de novo nem uma chave nova resolvem. |
| 403 | scope_not_allowed | A chave não tem o escopo que este endpoint exige. | Crie uma chave com os escopos certos, ou deixe os escopos vazios para liberar todos. |
| 403 | ip_not_allowed | A chave tem uma lista de IPs permitidos, e a requisição veio de um endereço fora dela. | Chame a partir de um IP permitido, ou crie uma chave com os IPs certos — ou sem nenhum, para aceitar qualquer IP. |
| 403 | account_suspended | A conta está suspensa, então todas as chaves dela são recusadas. | Fale com o suporte. Gerar outra chave não adianta. |
| 429 | api_key_rate_limited | Requisições demais no mesmo minuto para esta chave. | Espere e tente de novo após os segundos indicados no cabeçalho Retry-After. |
| 400 | (erros de campo) | O corpo da requisição tem algum erro. message aponta cada campo com problema. | Leia message — ele é específico. Nunca é cobrado. |
Vale repetir: 402 não é falha de autenticação. A chave está boa; o saldo é que zerou. Gerar outra chave é o erro mais comum e não muda nada.
Cabeçalhos de créditos
Toda resposta informa quanto a chamada custou e quanto sobrou, para você acompanhar o gasto sem uma segunda requisição.
X-Credits-Cost: 1 # what this endpoint costs
X-Credits-Charged: 1 # what you were actually billed — 0 on any error
X-Credits-Remaining: 149 # balance after this callO cabeçalho que vale registrar em log é o X-Credits-Charged. Uma requisição que falha sempre informa 0: o crédito é reservado antes de o cálculo rodar e devolvido se ele não terminar sem erro. Assim, uma integração com bug não esvazia o saldo enquanto você a depura.
Limites de requisições
Os limites valem por chave e por minuto, e existem para conter uma chave vazada, não para racionar seu uso. Se você passar do limite, recebe um 429 com o cabeçalho Retry-After em segundos — espere esse tempo em vez de tentar de novo na mesma hora. As respostas também trazem X-RateLimit-Limit e X-RateLimit-Remaining.
Um 429 nunca é cobrado. Se você bate no limite no uso normal, peça para a gente aumentar.
Como proteger sua chave
- Chame a API do seu servidor, não do navegador. Uma chave num bundle de front-end ou num app mobile é pública, seja qual for o nome dela. Qualquer um pode lê-la e gastar seu saldo.
- Guarde-a numa variável de ambiente ou num gerenciador de segredos. Nunca faça commit dela.
- Use uma chave por ambiente, para poder revogar uma sem derrubar as outras.
- Para trocar a chave, crie a nova, faça o deploy dela e só então revogue a antiga — nessa ordem, para nada ficar fora do ar no meio do caminho.
- Revogue na hora qualquer chave que possa ter vazado. A revogação vale imediatamente, e seus créditos restantes continuam intactos.
Faça tudo isso na sua página de chaves.