> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bookliftagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Créditos

> Qué consume, cuánto te queda y qué pasa al agotarlos.

## Qué cuesta un crédito

**Una conversación atendida = 1 crédito.** Da igual lo largo que sea el
mensaje o cuántos modelos haga falta consultar por dentro.

Se cobra por conversación y no por tokens a propósito: puedes estimar cuántas
conversaciones tendrás al mes; cuántos tokens, no.

Estas llamadas **no consumen créditos**:

* `GET /v1/yo`
* `GET /v1/negocios`
* `GET /v1/negocios/{id}`
* `GET /v1/uso`

## Consultar tu saldo

```bash theme={null}
curl https://api.bookliftagent.com/v1/yo \
  -H "Authorization: Bearer $BOOKLIFT_API_KEY"
```

```json theme={null}
{
  "creditos": { "limite_mes": 25000, "usados": 3120, "restantes": 21880, "periodo": "2026-08-01" }
}
```

El periodo es natural: se reinicia el día 1 de cada mes.

## Al agotarlos

La API responde `402` y **el agente deja de contestar**:

```json theme={null}
{
  "error": {
    "codigo": "sin_creditos",
    "mensaje": "Has agotado los créditos de este mes. Amplía tu plan para seguir.",
    "limite_mes": 25000,
    "periodo": "2026-08-01"
  }
}
```

<Warning>
  Un `402` significa que los clientes de tus negocios se quedan sin respuesta.
  No esperes a que ocurra: vigila `restantes` y avisa cuando bajes del 10%.
</Warning>

Una comprobación diaria basta:

```javascript theme={null}
const { creditos } = await fetch("https://api.bookliftagent.com/v1/yo", {
  headers: { Authorization: `Bearer ${process.env.BOOKLIFT_API_KEY}` },
}).then((r) => r.json());

if (creditos.limite_mes && creditos.restantes / creditos.limite_mes < 0.1) {
  avisarAlEquipo(`Quedan ${creditos.restantes} créditos de Booklift`);
}
```

## Cuando no se te cobra

* El agente **falla** (`502`): el crédito se devuelve automáticamente.
* **Reintentas** con la misma `Idempotency-Key`: se cobra una sola vez.
* La petición es **inválida** (`400`, `401`, `404`): no llega a haber cargo.

## Cuadrar tu factura

`GET /v1/uso` devuelve las últimas 100 llamadas facturadas, con negocio,
endpoint y fecha.