Pergunte antes de executar
O mesmo produto vendido a dois clientes pode ter tetos diferentes. A sua aplicação pergunta pelo limite antes de gerar custo, e a resposta chega na hora — sem chamada extra.
Limites por cliente, não por produto
O limite é uma propriedade do cliente, não da sua aplicação. Você define qual cliente tem qual recurso liberado, e a plataforma responde por ele.
| O que a sua aplicação pergunta | Como pergunta | O que recebe |
|---|---|---|
| Este cliente tem o recurso liberado? | /api/entitlements/check | 200, ou negado com o motivo da recusa |
| Quanto do limite já foi usado? | /api/entitlements/check | O consumo do ciclo, e um aviso aos 80% do limite |
| E vários recursos de uma vez? | /api/entitlements/check/bulk | 200, com a lista resolvida em uma chamada |
| O que acontece quando bate no teto? | Sem chamada extra | A execução para antes de gerar custo |
O que a sua aplicação precisa tratar
Quatro respostas cobrem a cobrança inteira. Todas chegam com um corpo explicando o motivo, para a sua aplicação decidir sem adivinhar.
| Resposta | O que significa | O que a sua aplicação faz |
|---|---|---|
| 202 | Cobrança aceita e debitada. | Segue o fluxo. Nada a reenviar. |
| 402 | Saldo insuficiente, ou o recurso não está liberado para este cliente. | Para antes de executar e chama a recarga. É o paywall. |
| 403 | A conta está bloqueada. | Interrompe o consumo e fala com a Nokr. |
| 429 | Limite de chamadas da chave foi atingido. | Espera e tenta de novo — a cobrança não passou. |
O 402 é o mesmo nas duas causas: falta de saldo e recurso não liberado. Um mecanismo só, e a sua aplicação já sabe o que fazer com ele.
O que sustenta as respostas acima
Cada uma destas é um comportamento da API, não uma promessa de contrato. É o que faz o limite ser confiável com dinheiro no meio.
A mesma chamada não cobra duas vezes
Se a rede falhar e o seu código repetir a chamada, o débito acontece uma vez só. Basta repetir o X-Idempotency-Key, e a segunda tentativa devolve a resposta da primeira em vez de debitar de novo.
Cada cliente no seu próprio espaço
Registro e saldo de cada cliente ficam isolados por namespace. Um cliente nunca lê o dado do outro, nem por engano de consulta.
Teto de chamadas por chave, resposta 429
Cada chave de API tem um teto de requisições. Acima dele a resposta é 429, e a cobrança não passa — um pico de tráfego não vira fatura surpresa.
Não guardamos os dados do seu cliente
A Nokr registra uso e saldo. O dado pessoal de quem paga fica com a instituição de pagamento autorizada, que é quem responde por ele.
O primeiro limite sai de uma conversa.
Em desenvolvimento. Quando a Produção abrir, ela vai exigir CNPJ ativo e aprovação cadastral. O time monta com você o primeiro recurso e o primeiro teto por cliente.