📈 Estatus de Consumo de API

Endpoint ligero para mostrar los créditos restantes de un API Key. Pensado para polling desde tu backend: no consume créditos y lee el saldo en vivo.

• Método: GET
• URL de Consumo: https://api.consultaunica.mx/v3/user-stats
• Rate limit: 10 peticiones por segundo por x-api-key.

Ejemplo de consumo

curl https://api.consultaunica.mx/v3/user-stats \
  -H 'x-api-key: 1a2b3c4d5e6f1a2b3c4d5e6f1a2b3c4d5e6f1a2b3c4d5e6f'

✅ Respuesta exitosa. HTTP 200

{
  "remainingCredits": 42
}

Campo	Tipo	Descripción
remainingCredits	int	Créditos disponibles. 0 significa saldo agotado — ya no significa "hubo un error".

remainingCredits es el nombre canónico del saldo en la API. Los endpoints POST /v3/info/usage y POST /v3/info/user-validate exponen el mismo número como remainingRequests, que se conserva por compatibilidad con integraciones existentes.

⚠️ Manejo de errores

Los errores se devuelven con el formato estándar de la API: message, description y errorCode. Programa contra errorCode.

Situación	HTTP	errorCode
Saldo agotado	200	— (remainingCredits: 0)
Header x-api-key ausente	401	missing_api_key
Clave inválida, o cuenta bloqueada / no confirmada / desactivada	401	unauthorized_user
Demasiados intentos con claves no válidas desde tu conexión	429	too_many_invalid_keys
Rate limit excedido	429	rate_limit_exceeded
Fallo interno	500	unknown

Saldo agotado y clave inválida son distinguibles. Sin créditos recibes 200 con remainingCredits: 0; con una clave que ya no sirve recibes 401. Son dos situaciones con acciones opuestas: comprar un paquete o revisar tu integración.

🔒 Protección contra pruebas de claves

Para evitar que este endpoint sirva para averiguar qué claves son válidas, contamos los fallos de autenticación por dirección IP. Tras 10 respuestas 401 desde la misma IP dentro de una ventana de 15 minutos, las siguientes peticiones reciben 429 con errorCode too_many_invalid_keys y un header Retry-After con los segundos restantes.

Solo cuentan los fallos: una clave válida nunca acumula, sin importar con qué frecuencia consultes tu saldo. El contador es compartido con POST /v3/info/usage y POST /v3/info/user-validate.

Si te topas con este error, casi siempre significa que la clave configurada en tu despliegue no es la correcta.

🚦 ¿El servicio está caído?

El saldo no explica un 5xx. Para saber si una consulta está fallando del lado de la plataforma y si hay un incidente activo, usa Estado del servicio e incidentes.