@page "/docs/erros"
@model Nalu.Web.Pages.Docs.ErrosModel
@{
    ViewData["Title"] = "Erros — NaLU AI Docs";
    ViewData["Description"] = "Códigos HTTP, payloads de erro e como lidar com rate limit e falhas de serviço na NaLU AI.";
}

<section class="bg-gradient-to-b from-slate-50 to-white pt-16 pb-8">
    <div class="max-w-3xl mx-auto px-4 sm:px-6">
        <div class="text-xs font-semibold text-nalu-600 uppercase tracking-wide mb-3">
            <a href="/docs" class="hover:underline">Docs</a> / Erros
        </div>
        <h1 class="text-3xl font-extrabold text-gray-900 mb-2">Erros</h1>
        <p class="text-gray-500">Todos os erros retornam JSON com campo <code class="bg-slate-100 px-1 rounded text-sm">error</code>.</p>
    </div>
</section>

<section class="py-10 bg-white">
    <div class="max-w-3xl mx-auto px-4 sm:px-6 space-y-10">

        <!-- 401 -->
        <div>
            <div class="flex items-center gap-3 mb-3">
                <span class="bg-yellow-100 text-yellow-700 font-bold text-sm px-3 py-1 rounded-full">401</span>
                <h2 class="text-lg font-bold text-gray-900">Unauthorized</h2>
            </div>
            <p class="text-sm text-gray-600 mb-3">API Key inválida, expirada ou ausente no header.</p>
            <div class="bg-slate-900 rounded-xl p-5 font-mono text-sm text-slate-300 overflow-x-auto">
<pre>{
  "error": "unauthorized",
  "message": "API Key inválida ou ausente."
}</pre>
            </div>
            <p class="text-xs text-gray-500 mt-2">Verifique o header: <code class="bg-slate-100 px-1 rounded">Authorization: Bearer SUA_API_KEY</code></p>
        </div>

        <!-- 429 rate limit -->
        <div>
            <div class="flex items-center gap-3 mb-3">
                <span class="bg-orange-100 text-orange-700 font-bold text-sm px-3 py-1 rounded-full">429</span>
                <h2 class="text-lg font-bold text-gray-900">Rate Limit (IP)</h2>
            </div>
            <p class="text-sm text-gray-600 mb-3">Mais de 60 req/min ou 500 req/hora do mesmo IP.</p>
            <div class="bg-slate-900 rounded-xl p-5 font-mono text-sm text-slate-300 overflow-x-auto">
<pre>{
  "error": "rate_limit_exceeded",
  "message": "Muitas requisições por minuto deste IP. Aguarde alguns segundos.",
  "retry_after_seconds": 60
}</pre>
            </div>
            <p class="text-xs text-gray-500 mt-2">Aguardar <code class="bg-slate-100 px-1 rounded">retry_after_seconds</code> antes de tentar novamente.</p>
        </div>

        <!-- 429 daily cap -->
        <div>
            <div class="flex items-center gap-3 mb-3">
                <span class="bg-orange-100 text-orange-700 font-bold text-sm px-3 py-1 rounded-full">429</span>
                <h2 class="text-lg font-bold text-gray-900">Limite Diário (Free)</h2>
            </div>
            <p class="text-sm text-gray-600 mb-3">Plano Free atingiu 100 créditos por dia.</p>
            <div class="bg-slate-900 rounded-xl p-5 font-mono text-sm text-slate-300 overflow-x-auto">
<pre>{
  "error": "daily_limit_exceeded",
  "message": "Limite diário de 100 créditos atingido no plano gratuito. Renova amanhã ou faça upgrade.",
  "credits_used": 100,
  "credits_limit": 100,
  "reset_at": "2026-05-11T00:00:00Z",
  "upgrade_url": "https://naluai.dev/precos",
  "hint": "Plano Starter: 15.000 créditos/mês sem limite diário. R$ 29/mês."
}</pre>
            </div>
        </div>

        <!-- 429 credits -->
        <div>
            <div class="flex items-center gap-3 mb-3">
                <span class="bg-orange-100 text-orange-700 font-bold text-sm px-3 py-1 rounded-full">429</span>
                <h2 class="text-lg font-bold text-gray-900">Créditos Esgotados</h2>
            </div>
            <p class="text-sm text-gray-600 mb-3">Limite mensal do plano atingido.</p>
            <div class="bg-slate-900 rounded-xl p-5 font-mono text-sm text-slate-300 overflow-x-auto">
<pre>{
  "error": "credits_exhausted",
  "message": "Seus créditos do mês acabaram. Seu plano (Free) permite 3.000 créditos/mês.",
  "credits_used": 3000,
  "credits_limit": 3000,
  "reset_at": "2026-06-01T00:00:00Z",
  "upgrade_url": "https://naluai.dev/precos",
  "hint": "Upgrade para Starter por apenas R$ 0,0058 por validação."
}</pre>
            </div>
        </div>

        <!-- 503 -->
        <div>
            <div class="flex items-center gap-3 mb-3">
                <span class="bg-red-100 text-red-700 font-bold text-sm px-3 py-1 rounded-full">503</span>
                <h2 class="text-lg font-bold text-gray-900">Service Unavailable</h2>
            </div>
            <p class="text-sm text-gray-600 mb-3">O motor de IA está temporariamente indisponível. O header <code class="bg-slate-100 px-1 rounded text-xs">Retry-After: 30</code> indica quando tentar.</p>
            <div class="bg-slate-900 rounded-xl p-5 font-mono text-sm text-slate-300 overflow-x-auto">
<pre># Headers na resposta:
Retry-After: 30

# Estratégia recomendada:
- Tentar novamente após 30 segundos
- Máximo 3 tentativas com backoff exponencial
- Após 3 falhas: retornar erro para o usuário</pre>
            </div>
        </div>

        <!-- obtained: false -->
        <div>
            <div class="flex items-center gap-3 mb-3">
                <span class="bg-green-100 text-green-700 font-bold text-sm px-3 py-1 rounded-full">200</span>
                <h2 class="text-lg font-bold text-gray-900">obtained: false (não é erro)</h2>
            </div>
            <p class="text-sm text-gray-600 mb-3">
                HTTP 200 com <code class="bg-slate-100 px-1 rounded text-xs">obtained: false</code> significa que o dado não foi encontrado na resposta do usuário.
                Não é um erro — use <code class="bg-slate-100 px-1 rounded text-xs">suggestion_to_agent</code> para perguntar novamente.
            </p>
            <div class="bg-slate-900 rounded-xl p-5 font-mono text-sm text-slate-300 overflow-x-auto">
<pre>{
  "obtained": false,
  "extracted_value": null,
  "certain": false,
  "confidence": "low",
  "suggestion_to_agent": "Desculpe, não consegui identificar seu CPF. Pode digitar apenas os números? Ex: 111.444.777-35"
}</pre>
            </div>
        </div>

        <!-- Backoff table -->
        <div>
            <h2 class="text-lg font-bold text-gray-900 mb-3">Estratégia de retry recomendada</h2>
            <table class="w-full text-sm border border-gray-100 rounded-xl overflow-hidden">
                <thead class="bg-gray-50">
                    <tr>
                        <th class="px-4 py-2 text-left font-semibold text-gray-700">Código</th>
                        <th class="px-4 py-2 text-left font-semibold text-gray-700">Retry?</th>
                        <th class="px-4 py-2 text-left font-semibold text-gray-700">Como</th>
                    </tr>
                </thead>
                <tbody class="divide-y divide-gray-50">
                    <tr><td class="px-4 py-2 font-bold text-yellow-600">401</td><td class="px-4 py-2 text-red-500">Não</td><td class="px-4 py-2 text-gray-600">Corrigir API Key</td></tr>
                    <tr><td class="px-4 py-2 font-bold text-orange-600">429 rate</td><td class="px-4 py-2 text-green-600">Sim</td><td class="px-4 py-2 text-gray-600">Aguardar <code class="text-xs bg-slate-100 px-1 rounded">retry_after_seconds</code></td></tr>
                    <tr><td class="px-4 py-2 font-bold text-orange-600">429 credits</td><td class="px-4 py-2 text-red-500">Não</td><td class="px-4 py-2 text-gray-600">Fazer upgrade ou aguardar reset mensal</td></tr>
                    <tr><td class="px-4 py-2 font-bold text-red-600">503</td><td class="px-4 py-2 text-green-600">Sim</td><td class="px-4 py-2 text-gray-600">Backoff: 30s, 60s, 120s</td></tr>
                </tbody>
            </table>
        </div>

        <div class="border-t border-gray-100 pt-6 flex gap-4">
            <a href="/docs" class="text-nalu-600 text-sm hover:underline">← Voltar para Docs</a>
            <a href="/docs/creditos" class="text-nalu-600 text-sm hover:underline">Créditos →</a>
        </div>
    </div>
</section>
