Errors, retries and usage

Know the pricing and credit policy

All model aliases and routing modes use one fixed 5% markup on the configured provider cost. Exact aliases and Kendr managed routing do not have different markup percentages. Credits added by a completed paid package purchase never expire; promotional grants can have a grant-specific expiration.

• Use the public catalog's pricing_policy and per-model pricing fields for public quotes.
• Use authenticated GET /v1/models for models and rates available to the current account.
• Use kendr_usage.credits_charged_micros as the authoritative settled model charge.
• Use the wallet activity or billing summary to distinguish non-expiring purchased lots from expiring promotional lots.

See Credits and billing for package and lot behavior.

Fetch surfaces, packages, and current credits

Use the public catalog to discover what is available, then use the customer dashboard to read the live wallet balance and package state for the authenticated user.

curl https://api.kendr.org/api/catalog

curl https://api.kendr.org/api/me/dashboard \
  -H "X-Kendr-Session: $KENDR_SESSION"

Read the model response envelope

Successful model responses add three Kendr blocks next to the compatibility-format fields. A trimmed /v1/responses result:

{
  "id": "0887c41b-5285-409d-ad04-b900b9a258c3",
  "model": "kendr-intelligent",
  "status": "completed",
  "output_text": "Hello! How can I help?",
  "usage": { "input_tokens": 36, "output_tokens": 25, "total_tokens": 61 },
  "kendr_usage": {
    "credits_charged": "0.01165",
    "credits_charged_micros": 11650,
    "remaining_credits": "49886.925505",
    "request_id": "0887c41b-5285-409d-ad04-b900b9a258c3",
    "pricing_version": "cloud-v1"
  },
  "kendr_routing": {
    "receipt_id": "kr_86f82eb4d7a54fa2b30d8ce43e7d5f72",
    "request_id": "0887c41b-5285-409d-ad04-b900b9a258c3",
    "policy_version": "balanced-v1",
    "catalog_version": "catalog-2026-08-12",
    "pricing_version": "cloud-v1",
    "rate_card_version": "2026-08-12T00:00:00Z",
    "requested_model": "kendr-intelligent",
    "selected_model_alias": "kc-llama-4-scout",
    "task_category": "flash",
    "reason_code": "trivial_greeting_cheapest_fast",
    "confidence": "0.95",
    "tools": [],
    "latency_ms": 842,
    "attempted_candidates": [
      {"attempt": 1, "selected_model_alias": "kc-llama-4-scout", "status": "succeeded", "latency_ms": 842}
    ],
    "usage": {
      "input_tokens": 36,
      "cached_input_tokens": 0,
      "cache_write_tokens": 0,
      "output_tokens": 25,
      "reasoning_tokens": 0,
      "total_tokens": 61
    },
    "cost": {
      "currency": "credits",
      "credits_charged_micros": 11650,
      "credits_charged": "0.01165"
    }
  },
  "kendr_optimization": {
    "enabled": true,
    "requested_mode": "balanced",
    "resolved_mode": "balanced",
    "engine": "kendr_optimizer",
    "estimated_input_tokens_avoided": 24,
    "estimated_credits_saved_micros": 4000,
    "estimated_credits_without_optimization_micros": 15650,
    "shadow": false
  }
}

Keep API keys out of client code

Store Kendr API keys in a server-side secret manager or protected environment variable. Never place a live key in browser JavaScript, a mobile bundle, a public repository, logs, analytics events, or support screenshots.

# Local development only
KENDR_API_KEY=kndr_live_replace_with_your_key

# Application configuration
KENDR_BASE_URL=https://api.kendr.org/v1
KENDR_MODEL=kendr-intelligent

• Create separate keys for development and production so one environment can be revoked without interrupting the other.
• Use the narrowest scopes your integration needs. Model listing needs models:read; generation needs models:invoke; usage reads need usage:read.
• Rotate a key by creating its replacement, updating callers, confirming traffic on the new key, and then revoking the old key.
• Proxy browser and mobile requests through your backend when your product cannot safely hold a server credential.

Kendr configuration reference

Use environment variables or protected deployment secrets for service configuration. Client applications normally need only KENDR_API_KEY, KENDR_BASE_URL, and the selected model alias.

Retries, timeouts, and idempotency

Idempotency-Key is optional — Kendr generates one per request when absent. Supplying your own key is recommended for production retry safety: reuse the same key only when retrying the same logical operation, and create a new key for a new user request.

Track usage without recording sensitive prompts

Record your own request identifier, idempotency key, selected Kendr alias, status, latency, token totals, and returned credit charge. Avoid logging authorization headers or full prompts unless your own privacy policy explicitly requires and protects that data.

curl https://api.kendr.org/api/me/billing/summary \
  -H "X-Kendr-Session: $KENDR_SESSION"

curl https://api.kendr.org/v1/models \
  -H "Authorization: Bearer $KENDR_API_KEY"

Build authenticated model selection from GET /v1/models at runtime. Use unauthenticated GET /api/public/models for public directories or pre-login discovery; its versioned response exposes public capabilities, availability, and credit rates but deliberately omits private provider routes and account-specific aliases. An alias can become temporarily unavailable, so avoid hardcoding assumptions about every account or environment.

Production checklist

• Create a production key with only the scopes the service requires and store it outside source control.
• Use TLS and the exact https://api.kendr.org API base domain.
• Generate an idempotency key for every chargeable operation and preserve it across retries.
• Handle 400, 401, 402, 429, and 5xx responses deliberately; cap retry attempts.
• Set connect, read, and overall deadlines appropriate to model latency.
• Read the model catalog at runtime and provide a graceful fallback when the preferred alias is unavailable.
• Monitor latency, failures, token usage, and credits charged without logging secrets.
• Test key rotation, low-credit behavior, duplicate retries, streaming disconnects, and revoked credentials before launch.