Saldo de Créditos

Devuelve el plan actual, los créditos restantes y usados, el estado de facturación y los identificadores de la cuenta. Es una consulta de solo lectura: no consume crédito y funciona incluso con saldo en cero.

⚠

Cambio del 4 de octubre de 2026

Desde hoy, GET /quota y la herramienta MCP get_quota_info dejan de devolver staticCreditCost, realtimeCreditCost, overageEnabled, overagePriceInCents, staticRateLimitPerMinute y realtimeRateLimitPerMinute. Los costos por consulta (1 crédito por defecto en la Consulta Simple y 1,5 en la Consulta en Tiempo Real) y las reglas de excedente de tu plan están en el dashboard. Los límites por defecto son 30/min en la Consulta Simple (cada envío de lote cuenta como 1) y 5/min en la Consulta en Tiempo Real. Los planes personalizados pueden tener límites distintos, así que confírmalo con el soporte de CPFHub.io. Las respuestas 429 traen el header Retry-After. Consulta Límites de Uso.

Endpoint

GEThttps://api.cpfhub.io/quota

Autenticación

Envía tu clave de API en el header x-api-key. Consulta Autenticación.

Parámetros

Este endpoint no recibe parámetros de path ni de query.

Headers

Header	Obligatorio	Descripción
`x-api-key`	Sí	Tu clave de API de CPFHub.io

Ejemplos de solicitud

curl "https://api.cpfhub.io/quota" \
  -H "x-api-key: $CPFHUB_API_KEY"

Respuesta exitosa

HTTP 200 OK

JSON

{
  "success": true,
  "data": {
    "plan": "Básico",
    "remainingCredits": 750,
    "usedCredits": 250,
    "billingStatus": "active",
    "userId": "123e4567-e89b-12d3-a456-426614174000",
    "email": "usuario@exemplo.com"
  }
}

Campos de la respuesta

Campo	Tipo	Descripción
`success`	`boolean`	`true` si la solicitud se procesó correctamente
`data.plan`	`string`	Nombre del plan de tu suscripción: `Grátis`, `Micro`, `Básico`, `Intermediário`, `Avançado` o un plan personalizado. Son los nombres en portugués que devuelve la API, y el plan Pro del sitio corresponde a Micro, Básico, Intermediário o Avançado según el volumen (consulta Límites de Uso). Las cuentas sin suscripción devuelven `"unknown"`
`data.remainingCredits`	`integer`	Créditos que aún quedan en la franquicia del período, redondeados hacia abajo. Un saldo de 1,4 aparece como `1`. Nunca queda negativo: en planes con excedente se mantiene en `0` mientras las consultas se siguen cobrando como excedente
`data.usedCredits`	`number`	Créditos consumidos por toda la cuenta (todas las claves) en el período actual. En planes de pago, el período es el ciclo de facturación de la suscripción. En el plan Gratis, es el mes en curso (UTC). Puede tener decimales y superar la franquicia en planes con excedente
`data.billingStatus`	`"active"` \| `"free"`	Elegibilidad al plan: `"active"` cuando la cuenta tiene una suscripción que da acceso al plan, incluida una suscripción en el plan Gratis y estados como `past_due`. `"free"` cuando no hay suscripción válida, por ejemplo `canceled`, `unpaid` o `incomplete_expired`. En ese caso, `plan` puede venir como `"unknown"`
`data.userId`	`string`	Identificador único del usuario
`data.email`	`string`	Dirección de correo electrónico asociada a la cuenta

✦

Funciona con saldo en cero

GET /quota sigue respondiendo cuando el saldo de créditos llega a cero. Así puedes consultar el saldo desde tu sistema y anticiparte antes de que las consultas se detengan.

ℹ

Saldo fraccionado

La Consulta Simple cuesta 1 crédito y la Consulta en Tiempo Real cuesta 1,5 créditos por defecto, así que el saldo puede quedar fraccionado. Como remainingCredits se redondea hacia abajo, revisa los costos específicos de tu plan en el dashboard antes de decidir si el saldo cubre la siguiente consulta.

Cómo monitorear el saldo

Crea una alerta cuando remainingCredits baje de un umbral tuyo (por ejemplo, 10% de la franquicia).
Sigue usedCredits para medir el consumo total del período.
Revisa en el dashboard los costos y las reglas de excedente específicas de tu plan.
Los límites por defecto son 30/min en la Consulta Simple (cada envío de lote cuenta como 1) y 5/min en la Consulta en Tiempo Real. Los planes personalizados pueden tener límites distintos, así que confírmalo con el soporte de CPFHub.io. Por encima del límite, la API responde 429 con el header Retry-After.
La franquicia del período es usedCredits + remainingCredits mientras el saldo no llegue a cero.

Códigos de estado

Estado	Descripción
`200 OK`	Consulta de saldo exitosa
`401 Unauthorized`	Clave de API ausente, inválida o inactiva
`403 Forbidden`	Cuenta inactiva o bloqueada
`500 Internal Server Error`	Error interno al validar la suscripción (`"Erro ao validar assinatura"`, error al validar la suscripción)
`503 Service Unavailable`	Saldo temporalmente no disponible (`error: "usage_unavailable"`). Intenta de nuevo en unos segundos.

En estos errores, error viene como cadena. GET /quota no tiene límite por minuto y no consume crédito.

⚠

Mantén tu clave de API segura

Nunca expongas tu clave de API en código público, repositorios ni aplicaciones que se ejecutan directamente en el navegador. Haz las llamadas a la API siempre desde tu back end o servidor.

Para ver la lista completa de códigos de error y mensajes, consulta Códigos de Error.

Actualizado el 3 de octubre de 2026