Troubleshooting

Credit and limit errors

Troubleshoot credit and limit errors in Ottili ONE: insufficient-credit rejections, budget and model limits, HTTP 429 rate-limit errors on the Unified API, and wallet/quota mismatches — with verified routes, statuses and surfaces.

Overview

This article covers credit and limit errors* in Ottili ONE — the messages and failures you can hit when an AI request, an Ottili Coder run, a Unified API call or an Ottili HQ action is stopped because of credits or a limit.

Two independent systems can stop a request, and the error tells you which:

Credits (AI usage):* every AI request across Ottili ONE draws from one company wallet*. Billing is prepaid on company credits, and a request with insufficient funds is fail-closed* — rejected with a clear error, never silently overspent.
Limits (rate, budget, model, quota):* the Unified API ottili-ai-api-rate-limits per company, and cost control enforces per-key and per-company budget and model limits.

All interactive surfaces run through the Ottili ONE dashboard at [dashboard.ottili.one](https://dashboard.ottili.one); the developer surface is the Unified API at https://api.ottili.one/api/v1. The public website (ottili.one) points to the dashboard for every account and usage step.

Feature note:* AI credits, cost control and Unified API rate limiting are Live (General Availability)*. Which exact models, budgets and rate quotas apply depends on your plan and configuration — the values are returned in API headers and shown in the dashboard, so never hardcode them. For what the status labels Live, Beta, Private Beta, In Development, Planned and Concept mean, see [Understand feature status labels](/docs/understand-feature-status-labels).

Prerequisites

Before you start troubleshooting, check these points:

You are signed in to the correct company* — credit balances and limits are company-scoped (company_id), so the wrong company context shows the wrong wallet or limits.
You know which surface* produced the error: Ottili AI chat, an Ottili Coder run, a Unified API call, or an Ottili HQ action.
You can open the dashboard and view the wallet / usage for the company in question.

Common credit and limit errors

"Insufficient credits" — the request is rejected (fail-closed)

AI requests are billed prepaid on company credits*. If the wallet balance is too low, the request is rejected with a clear error and no credits are spent.

What to check:

1. Open the dashboard and confirm the company wallet balance. Each company has exactly one wallet with two balances:

- Included monthly credits* — granted by your plan, reset at the start of each billing period.

- Top-up credits* — added when you buy credit packs; they sit above the included balance and are only used once the included credits are exhausted.

2. If the included credits ran out, either wait for the next monthly reset or buy a top-up credit pack.

3. Reservations are released when a request does not execute (for example, one that is rejected), so you only pay for work that actually happened.

How credits, the wallet and top-ups relate is described in [Credits and cost trace](/docs/understand-plans-and-credits).

A long run stops because of a budget limit

Cost control enforces budget limits* per API key and per company. A budget limit is designed to stop long automations — for example an Ottili Coder run — before unexpected overspend.

What to check:

1. Identify which API key the run used, and check its cost-control budget.

2. Increase or adjust the per-key or per-company budget, or split the work into smaller runs.

3. If you cannot change key settings, ask an Owner or Admin in your company.

A request is rejected by a model limit

Cost control also enforces model limits* per API key — deciding which models (for example Vale or Cairn) are allowed through a key.

What to check:

1. Switch to a model that the key allows, or have an Owner/Admin allow the model on that key.

2. If you are calling the Unified API directly, confirm the key's allowed-model list includes the model you requested.

HTTP 429 "Too Many Requests" (Unified API / client)

The Unified API ottili-ai-api-rate-limits per company* using a token-bucket algorithm. When the bucket is empty, the API responds with 429 Too Many Requests and a Retry-After header. The exact limit and remaining quota are returned in RateLimit-* response headers. Under high system load, adaptive throttling engages and non-critical endpoints are throttled more aggressively.

What to do:

1. Read the response headers instead of hardcoding limits:

- RateLimit-Limit — maximum allowed requests in the current window.

- RateLimit-Remaining — remaining requests in the current window.

- RateLimit-Reset — Unix timestamp when the window resets.

2. Honor Retry-After and back off; add client-side retry with jitter rather than tight loops.

3. Spread load over time and across windows. Some endpoints are excluded from rate limiting — do not rely on that for capacity planning.

Rate limiting in the Unified API is Live* (contract T-STAB-W7-CONTRACT-0022, effective 2026-07-09). Full detail is in [Rate limits](/docs/ottili-ai-api-rate-limits).

The wallet or quota looks wrong in the dashboard

Because there is exactly one company wallet per company, a mismatch usually means one of:

Wrong company context* — you are viewing a different company's wallet. Switch the active company in the dashboard.
Timing* — included credits reset at the start of each billing period; top-up credits are only consumed after the included balance is exhausted.
Reservation still held* — a request that has not yet executed may still hold a reservation; it is released when the request finishes or is rejected.

Every AI action is resolved to exactly one company (company_id) and recorded through Ottili Core Audit, so spend is fully traceable. See [Credits and cost trace](/docs/understand-plans-and-credits) and [Audit logs across products](/docs/audit-logs).

An invoice or payment is blocked or stuck (Ottili HQ)

In Ottili HQ, invoices and payments are company-scoped and Live*. If a payment cannot be allocated, the invoice moves to the payment_issue state — it is never silently marked paid. Open items are the invoices still in open, partial, overdue or payment_issue.

What to check:

1. Open the invoice and read its status (open, partial, overdue, payment_issue).

2. Resolve the provider or validation problem behind payment_issue; once fixed, the invoice can move toward paid.

3. If a dunning/reminder or overdue state is unexpected, confirm the company context and the collection policy.

Detail is in [Invoices and payment state](/docs/invoices-and-payments).