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

# Créditos

> Quanto cada resposta custa, o parâmetro include e como acompanhar o saldo.

A cota mensal é contada em **créditos por questão liberada**, não em
requisições nem em exibições. Cada camada de uma questão é cobrada **uma vez por
ciclo**, na primeira vez que ela chega à sua organização. Uma lista de 5
questões custa o mesmo que buscar essas 5 questões uma a uma pelo ID.

## Quanto custa uma questão

| Camada | O que traz | Créditos por questão |
| - | - | - |
| Questão | `statement`, `alternatives` (letra e texto), `exam`, `subject`, `year`, `difficulty` | 3 |
| Gabarito | `correctAlternative` e `alternatives[].isCorrect` | +3 |
| Resolução comentada | `resolution` | +6, só quando a questão tem resolução |

Sem `include`, a resposta traz a questão com gabarito: **6 créditos por
questão**.

Custam **0**:

* `GET /v1/vestibulares/exams` e `GET /v1/vestibulares/subjects`;
* uma lista que não encontrou nenhuma questão;
* qualquer resposta de erro, `4xx` ou `5xx`, `429` inclusive.

## Reler não cobra

Uma questão já liberada no ciclo pode ser pedida de novo quantas vezes quiser,
por qualquer chave da organização, sem gastar crédito:

| Situação | Custo |
| - | - |
| Primeira vez que a questão chega, com gabarito | 6 |
| Primeira vez, `include=none` | 3 |
| Reler a mesma questão no ciclo | 0 |
| Pedir o gabarito de uma questão já lida sem ele | 3 (só o gabarito) |
| Pedir a resolução de uma questão já lida | 6, se ela tiver resolução |

O ciclo é o da sua assinatura e recomeça todo mês, também nos planos anuais:
nada se acumula. A reserva da próxima seção continua sendo o pior caso; o que
vale é o custo cobrado, em `X-Credits-Charged`.

## Questões distintas por ciclo

Cada plano limita quantas questões **diferentes** a organização libera por
ciclo, em qualquer camada (`include=none` conta):

| Plano | Questões distintas por ciclo |
| - | - |
| Free | 60 |
| Starter | 8.000 |
| Pro | 16.000 |
| Business | 30.000 |
| Enterprise | negociado |

Releitura nunca conta nem é recusada, mesmo no limite. Uma página que traria
questões ainda não liberadas além do limite volta inteira como `429` com
`code: "DISTINCT_LIMIT_REACHED"`, sem custo e sem questões parciais. O contador
de distintas é por organização, não por exame nem por matéria.

Para acompanhar, toda resposta de questões traz o seu saldo de distintas:

| Header | Significado |
| - | - |
| `X-Distinct-Used` | Questões distintas já liberadas no ciclo, contando esta resposta. |
| `X-Distinct-Limit` | Teto do ciclo, já com os blocos extras. |
| `X-Distinct-Remaining` | Quantas questões novas ainda cabem. Peça `limit` menor que isso perto do teto. |

O `429` de distintas traz o mesmo saldo no corpo (`distinct_used`,
`distinct_limit`, `distinct_remaining`) e a mensagem diz quantas ainda cabem.
Quando `distinct_remaining` é maior que zero, repetir o pedido com `limit` menor
passa. O aviso por e-mail chega aos 80%, 90% e 100% do teto, uma vez por ciclo
cada, para o e-mail de cobrança da organização ou, sem ele, para os membros.

Os dois limites medem coisas diferentes: as **questões distintas** limitam a
abrangência (quantas questões você vê) e os **créditos** limitam a profundidade
(o que você pede de cada uma). A cota de créditos é de 9 por questão distinta.
Enquanto não houver resolução comentada, uma questão custa no máximo 6 créditos
(3 do enunciado e 3 do gabarito), então o limite de distintas se esgota antes
dos créditos. Com a resolução (+6), os créditos passam a pesar.

### Bloco extra

Nos planos pagos (Starter, Pro e Business), dá para ampliar o ciclo com um
\*\*bloco extra de +10.000 questões distintas e +90.000 créditos por R$ 400**
(cerca de R$ 0,04 por questão distinta). Os dois limites sobem juntos: o de
distintas e a cota mensal de créditos (9 créditos por questão distinta). Sem
excedente, o bloco é a única forma de ir além da cota no mesmo ciclo. É um
pagamento único, feito no painel, em
[Faturamento](https://platform.enemhub.com.br/dashboard/billing):

* vale só para o ciclo em que foi comprado e não acumula para o seguinte;
* cada ciclo comporta até 5 blocos (+50.000); passando disso, o caminho é um
  plano maior;
* o bloco é liberado quando o pagamento é confirmado, não ao abrir o checkout;
* o Free e o Enterprise não compram blocos: o Free faz upgrade e o Enterprise
  não tem limite de distintas.

Os dois `429` — o de cota de créditos e o `DISTINCT_LIMIT_REACHED` — já
avisam quando um bloco resolve. Planos antigos contados em requisições não
ganham créditos com o bloco.

## Escolher as camadas com `include`

`GET /v1/vestibulares/questions` e `GET /v1/vestibulares/questions/{id}` aceitam `include`,
com as camadas separadas por vírgula:

| `include` | Resposta | Créditos por questão |
| - | - | - |
| omitido ou `gabarito` | questão + gabarito, como sempre foi | 6 |
| `none` | só a questão | 3 |
| `gabarito,resolucao` | questão + gabarito + resolução comentada | 12 com resolução, 6 sem |
| `resolucao` | questão + resolução comentada, sem gabarito | 9 com resolução, 3 sem |

Qualquer outro valor devolve `400` e não custa nada.

```bash Só os enunciados, 3 créditos cada theme={null}
curl -G https://api.enemhub.com.br/v1/vestibulares/questions \
  -H "X-API-Key: $ENEMHUB_API_KEY" \
  -d year=2023 \
  -d limit=5 \
  -d include=none
```

Duas regras para ler a resposta:

* **Camada não pedida não aparece.** Com `include=none`, a questão vem sem
  `correctAlternative` e as alternativas vêm sem `isCorrect`. Sem `resolucao`,
  não existe o campo `resolution`.
* **Camada pedida que a questão não tem vem `null`, e não é cobrada.** Uma
  questão sem resolução, com `include=gabarito,resolucao`, vem com
  `"resolution": null` e custa 6. Uma questão sem gabarito vem com
  `"correctAlternative": null` e `isCorrect: null` em todas as alternativas, e
  custa 3.

> [!NOTE]
>
> `isCorrect: null` quer dizer "sem gabarito", não "alternativa errada". Trate
> os três valores: `true`, `false` e `null`.

```json Uma questão com include=gabarito,resolucao theme={null}
{
  "id": "f1ee873f-...",
  "statement": "<p>...</p>",
  "correctAlternative": "A",
  "resolution": "<p>A parábola corta o eixo y em (0, −1)...</p>",
  "alternatives": [
    { "id": "...", "letter": "A", "text": "f(x) = x² − 1", "isCorrect": true },
    { "id": "...", "letter": "B", "text": "f(x) = x² + 1", "isCorrect": false }
  ]
}
```

`resolution` é HTML, como `statement`: renderize sanitizado.

## A reserva

Antes de executar uma lista, a API reserva o pior caso: `limit × créditos por
questão` das camadas pedidas. Depois da resposta, cobra só o que foi entregue e
devolve a sobra ao saldo.

| Requisição | Reserva | Entregou | Custo |
| - | - | - | - |
| `limit=5` | 30 | 5 questões com gabarito | 30 |
| `limit=5` | 30 | 2 questões (última página) | 12 |
| `limit=5&include=none` | 15 | 5 questões | 15 |
| `limit=5` sem resultado | 30 | nada | 0 |

A busca por ID reserva o custo de uma questão com as camadas pedidas.

> [!WARNING]
>
> Perto do fim do saldo, uma página grande pode receber `429` mesmo quando uma
> menor caberia: a reserva é recusada se não couber no que resta. A mensagem do
> `429` diz quanto a requisição reservou e quanto resta no ciclo. Reduza
> `limit` ou tire camadas de `include` e tente de novo.

```json 429 por reserva theme={null}
{
  "error": "Too Many Requests",
  "code": "QUOTA_EXCEEDED",
  "message": "Limite mensal de créditos do plano excedido. Faça upgrade em https://platform.enemhub.com.br/dashboard/billing. Esta requisição reserva até 120 créditos e restam 40 no ciclo; reduzir `limit` ou `include` pode caber no saldo."
}
```

## Plano Free

O Free é permanente, com o acervo completo e dois limites por ciclo mensal:
**60 questões distintas** e **540 créditos**. Reler uma questão já liberada não
conta nem gasta crédito, então o limite que vale é o de 60 questões: 60 com
gabarito custam 360 créditos, e os 180 restantes só se gastam com resolução
comentada. A cota renova a cada ciclo; acabou antes, a resposta é `429` até a
renovação.

## Listas e o padrão de `limit`

A lista padrão é `limit=20` com gabarito: reserva 120 créditos, quase um quarto
do mês do Free. Os exemplos desta documentação usam `limit=5`, para pedir só a
página que vai ser exibida.

## Acompanhar o saldo

Toda resposta de `/v1/vestibulares/*` diz quanto custou e quanto resta:

| Header | Significado |
| - | - |
| `X-Credits-Charged` | Créditos que esta resposta custou. |
| `X-Credits-Remaining` | Créditos que restam no ciclo, já descontada esta resposta. |
| `X-Quota-Unit` | `credit`. Em planos contratados antes dos créditos, `request`. |
| `X-Quota-Limit` | Cota do plano no ciclo. |
| `X-Quota-Used` | Quanto a organização já usou no ciclo, somando todas as chaves. |
| `X-Quota-Overage` | Sempre `false`: não há excedente. |

```bash theme={null}
curl -si "https://api.enemhub.com.br/v1/vestibulares/questions?limit=5" \
  -H "X-API-Key: $ENEMHUB_API_KEY" | grep -iE "^x-(credits|quota)"
```

```
x-quota-limit: 100000
x-quota-unit: credit
x-credits-charged: 30
x-credits-remaining: 87970
x-quota-used: 12030
x-quota-overage: false
```

O saldo do ciclo também aparece no painel, na
[Visão geral](https://platform.enemhub.com.br/dashboard) e em
[Faturamento](https://platform.enemhub.com.br/dashboard/billing).

> [!NOTE]
>
> Planos contratados antes da cobrança por créditos continuam contando **1 por
> requisição** até a migração combinada com você, e respondem com
> `X-Quota-Unit: request`. Neles `X-Credits-Charged` também aparece, mostrando
> quanto a requisição custaria em créditos, sem descontar nada da cota.

Os limites por minuto e por dia e o `429` estão em
[Autenticação](/vestibulares/autenticacao.md#limites).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.