@page "/en/docs/errors"
@model Nalu.Web.Pages.En.Docs.EnErrorsModel
@{
    ViewData["LangPrefix"] = "/en";
    ViewData["PtUrl"] = "/docs/erros";
    ViewData["Title"] = "Errors — NaLU AI Docs";
    ViewData["Description"] = "HTTP codes, error payloads and how to handle rate limits and service failures in 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="/en/docs" class="hover:underline">Docs</a> / Errors
        </div>
        <h1 class="text-3xl font-extrabold text-gray-900 mb-2">Errors</h1>
        <p class="text-gray-500">HTTP codes, error payloads and handling strategies.</p>
    </div>
</section>

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

        <div>
            <h2 class="text-xl font-bold text-gray-900 mb-4">Error payload</h2>
            <p class="text-gray-600 mb-3">All errors return JSON with the same structure:</p>
            <div class="bg-slate-900 rounded-xl p-4 font-mono text-sm text-slate-300">
<pre>{
  "error":   "error_code",
  "message": "Human-readable description",
  "details": { }  // optional
}</pre>
            </div>
        </div>

        <div>
            <h2 class="text-xl font-bold text-gray-900 mb-4">HTTP status codes</h2>
            <div class="space-y-4">
                @foreach (var err in new[] {
                    ("200", "green", "OK", "Success.", ""),
                    ("400", "yellow", "Bad Request", "Missing or invalid field. Check the required fields in the request body.", "{ \"error\": \"validation_error\", \"message\": \"agent_input is required\" }"),
                    ("401", "red", "Unauthorized", "Invalid or missing API key. Check the Authorization header.", "{ \"error\": \"invalid_api_key\", \"message\": \"API key not found\" }"),
                    ("402", "red", "Payment Required", "Insufficient credits. Upgrade your plan or wait for the monthly reset.", "{ \"error\": \"insufficient_credits\", \"message\": \"0 credits remaining\" }"),
                    ("429", "red", "Too Many Requests", "Rate limit exceeded. See the Retry-After header for when to retry.", "{ \"error\": \"rate_limit_exceeded\", \"message\": \"60 req/min limit\" }"),
                    ("500", "red", "Internal Server Error", "Unexpected error on our end. Retry with exponential backoff.", "{ \"error\": \"internal_error\", \"message\": \"Please retry\" }"),
                })
                {
                    <div class="border border-gray-100 rounded-xl p-5">
                        <div class="flex items-center gap-3 mb-2">
                            <span class="font-mono font-bold text-@err.Item2-600">@err.Item1</span>
                            <span class="font-semibold text-gray-800">@err.Item3</span>
                        </div>
                        <p class="text-sm text-gray-600 mb-2">@err.Item4</p>
                        @if (!string.IsNullOrEmpty(err.Item5))
                        {
                            <div class="bg-slate-900 rounded-lg p-3 font-mono text-xs text-slate-300">@err.Item5</div>
                        }
                    </div>
                }
            </div>
        </div>

        <div>
            <h2 class="text-xl font-bold text-gray-900 mb-4">Handling rate limits (429)</h2>
            <p class="text-gray-600 mb-3">Check the <code class="bg-slate-100 px-1.5 py-0.5 rounded text-xs">Retry-After</code> header and implement exponential backoff:</p>
            <div class="bg-slate-900 rounded-xl p-4 font-mono text-sm text-slate-300">
<pre>async function callWithRetry(url, body, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const res = await fetch(url, { method: 'POST', body: JSON.stringify(body) });
    if (res.status !== 429) return res;

    const retryAfter = res.headers.get('Retry-After') ?? 60;
    await new Promise(r => setTimeout(r, retryAfter * 1000 * Math.pow(2, i)));
  }
  throw new Error('Max retries exceeded');
}</pre>
            </div>
        </div>

        <div>
            <h2 class="text-xl font-bold text-gray-900 mb-4">SmartSuggestion — when obtained=false</h2>
            <p class="text-gray-600 mb-3">When the validator can't extract the data, use <code class="bg-slate-100 px-1.5 py-0.5 rounded text-xs">smart_suggestion</code> to re-ask the user in context:</p>
            <div class="bg-slate-900 rounded-xl p-4 font-mono text-sm text-slate-300">
<pre>{
  "obtained":        false,
  "extracted_value": null,
  "smart_suggestion": "Could you rephrase? I need just your full name, e.g.: 'John Smith'",
  "credits_used":    3
}</pre>
            </div>
        </div>
    </div>
</section>
