Autenticación
Una cabecera, una clave y unos pocos errores, cada uno con un significado concreto.
La cabecera
Envía tu clave en la cabecera X-API-Key en cada solicitud. No hay flujo OAuth, ni intercambio de tokens, ni nada que 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 de la clave
Las claves tienen esta forma: yt_live_a1b2c3d4_x9K2mQ7vB4nR8sL1wY6tZ3pC5hJ0dF. Es decir, marca, entorno, un prefijo público de ocho caracteres y, al final, el secreto.
yt_live_…gasta créditos reales de tu saldo.yt_test_…es para desarrollo y aparece marcada como tal en tu registro de uso.
El prefijo es público y está indexado a propósito: si una clave se filtra en un repositorio público, se puede localizar y revocar solo con el prefijo, sin que nadie necesite la parte secreta.
Se muestra una vez y se guarda como hash
La clave se muestra una sola vez: cuando la creas. Solo guardamos un hash SHA-256, así que ni un administrador ni una copia de la base de datos pueden recuperarla. Por eso, aunque quisiéramos, no podríamos volver a enviártela. Después solo verás el prefijo y los cuatro últimos caracteres, suficiente para distinguir una clave de otra en la lista.
¿Has perdido una clave? Crea otra y revoca la antigua. Es más rápido que pedírnoslo, y es lo único que podríamos hacer nosotros.
Errores (y cuáles no tienen que ver con la autenticación)
Todos los errores usan la estructura habitual, con is_error: true y un código fijo, pensado para máquinas, en message. Decide según el código, no según el texto.
| Estado | message | Qué significa | Qué hacer |
|---|---|---|---|
| 401 | invalid_api_key | Falta la clave, tiene un formato incorrecto, está revocada o ha caducado. | Comprueba que la cabecera X-API-Key nos llega de verdad. Si has rotado la clave, despliega la nueva. |
| 402 | insufficient_credits | La clave es válida, pero no queda saldo. | Mejora tu plan o espera al reinicio mensual. No es un problema de autenticación: regenerar la clave no sirve de nada. |
| 403 | endpoint_not_allowed | Esa ruta no está disponible para claves de API: la ruta o el método no son correctos, o el endpoint se ha retirado. | Comprueba la ruta y el método en la referencia. No se arregla reintentando ni con una clave nueva. |
| 403 | scope_not_allowed | La clave no tiene el permiso (scope) que pide este endpoint. | Crea una clave con los scopes adecuados, o déjalos vacíos para tenerlos todos. |
| 403 | ip_not_allowed | La clave solo admite ciertas IP y la solicitud viene de una dirección que no está en la lista. | Llama desde una IP permitida o crea una clave con las IP correctas (o sin ninguna, para admitir cualquiera). |
| 403 | account_suspended | La cuenta está suspendida, así que se rechazan todas sus claves. | Escribe a soporte. Regenerar la clave no lo arregla. |
| 429 | api_key_rate_limited | Demasiadas solicitudes en un minuto con esta clave. | Espera los segundos que indica la cabecera Retry-After y vuelve a intentarlo. |
| 400 | (errores de campo) | El cuerpo de la solicitud no es correcto. message indica cada campo con error. | Lee message: es muy concreto. Nunca se cobra. |
Vale la pena repetirlo: un 402 no es un fallo de autenticación. La clave está bien; lo que falta es saldo. Regenerar la clave es el error típico, y no cambia nada.
Cabeceras de créditos
Cada respuesta indica lo que ha costado la llamada y el saldo que te queda, así que puedes controlar el gasto sin otra solicitud.
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 callLa que conviene registrar es X-Credits-Charged. Una solicitud fallida siempre marca 0: el crédito se reserva antes del cálculo y se libera si este no termina bien. Mientras depuras, una integración con errores no puede vaciarte el saldo.
Límites de solicitudes
Los límites van por clave y por minuto, y existen para frenar una clave filtrada, no para racionarte el uso. Si superas uno, recibes un 429 con la cabecera Retry-After, en segundos: espera ese tiempo antes de reintentar. Las respuestas también traen X-RateLimit-Limit y X-RateLimit-Remaining.
Un 429 nunca se cobra. Si llegas al límite con un uso normal, pídenos que lo subamos.
Cómo proteger tu clave
- Llama desde tu servidor, no desde el navegador. Una clave dentro del código de front-end o de una app móvil es pública, digas lo que digas. Cualquiera puede leerla y gastar tu saldo.
- Guárdala en una variable de entorno o en un gestor de secretos. Nunca la subas al repositorio.
- Usa una clave distinta para cada entorno: así puedes revocar una sin dejar sin servicio a las demás.
- Para rotarla, crea la clave nueva, despliégala y después revoca la antigua. En ese orden, para que nada deje de funcionar entre medias.
- Si una clave puede haberse filtrado, revócala enseguida. La revocación es inmediata y no afecta a los créditos que te quedan.
Todo esto se gestiona en tu página de claves.