Errors — NaLU AI Docs

Error payload

All errors return JSON with the same structure:

{
  "error":   "error_code",
  "message": "Human-readable description",
  "details": { }  // optional
}

HTTP status codes

200 OK

Success.

400 Bad Request

Missing or invalid field. Check the required fields in the request body.

{ "error": "validation_error", "message": "agent_input is required" }

401 Unauthorized

Invalid or missing API key. Check the Authorization header.

{ "error": "invalid_api_key", "message": "API key not found" }

402 Payment Required

Insufficient credits. Upgrade your plan or wait for the monthly reset.

{ "error": "insufficient_credits", "message": "0 credits remaining" }

429 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 Internal Server Error

Unexpected error on our end. Retry with exponential backoff.

{ "error": "internal_error", "message": "Please retry" }

Handling rate limits (429)

Check the Retry-After header and implement exponential backoff:

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');
}

SmartSuggestion — when obtained=false

When the validator can't extract the data, use smart_suggestion to re-ask the user in context:

{
  "obtained":        false,
  "extracted_value": null,
  "smart_suggestion": "Could you rephrase? I need just your full name, e.g.: 'John Smith'",
  "credits_used":    3
}