---
url: https://docs.consultaunica.mx/usage.md
description: >-
  Endpoint para consultar los créditos restantes de tu API Key. No consume
  créditos y lee el saldo en vivo, pensado para polling desde tu backend.
---

# 📈 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

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

## ✅ Respuesta exitosa. HTTP 200

```json
{
  "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](/services/imss/sc_premium.html#formato-de-las-respuestas-de-error) 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](./status.md).
