FAQ & troubleshooting
Recover from missing or invalid keys, rate limits and quota errors, provider failures, plus answers on iOS status, model capabilities, and cost estimates.
Answers for the published v0.5.0 baseline and the current source behavior documented in this guide, grouped by topic.
Setup & keys
"Check your API key" — my key isn't working
This is an auth failure (HTTP 401/403). Open Settings, re-paste the key for that provider, and make sure there's no stray whitespace. A blank key is treated as no key, so the provider will show as not configured. Keys are stored per provider, so each provider needs its own key — a key saved for OpenRouter won't authenticate OpenAI.
Where do I get an API key?
From the provider's own console, not from Cordy. See Getting started → where to get a key for step-by-step links for OpenRouter, OpenAI, Anthropic, Vercel AI Gateway, and Volcengine Ark.
After saving a key, the model list didn't fill in
Cordy loads a provider's catalog once a valid key is saved. If it stays on the small bootstrap list, the key is probably missing or rejected — re-check it. You can also tap Refresh models. For Anthropic (native), the model entry is built in rather than fetched, so the list won't grow from a /models call.
Can I use a self-hosted or in-house endpoint?
Yes — add it as a custom OpenAI-compatible provider. HTTPS is required except for loopback / private-LAN hosts, where plain http:// is allowed for local development.
Errors & recovery
Cordy maps provider and network failures to short, safe messages — raw provider responses, API keys, and auth headers are never shown.
| Message | Meaning | HTTP | Retryable? | What to do |
|---|---|---|---|---|
| Check your API key and try again. | Invalid / expired key | 401 / 403 | No | Fix the key in Settings |
| Provider credits exhausted. Top up your account and try again. | Out of credits | 402 | No | Add credits/billing with the provider |
| Provider is rate limited. Try again later. | Rate limit | 429 | Yes (later) | Wait, then Retry |
| This conversation is too long. Start a new chat or shorten the history. | Context window exceeded | — | No | New chat, or remove old context |
| Provider rejected this request. Try a different model or adjust settings. | Invalid request | 400 | No | Change model / adjust settings |
| Provider had an issue. Try again. | Provider server error | 5xx | Yes | Retry |
| Network timeout / Network unavailable / request failed. | Transport problem | — | Yes | Check connection, Retry |
| Local database / Secure storage failed. | On-device storage error | — | No | Retry the action; if it persists, restart |
Retryable errors surface a Retry action. If a stream is interrupted by a crash or force-quit, the next launch cleanly marks it Stopped, and you can Regenerate.
"Provider credits exhausted" (402)
Your account is out of credits or has no billing set up. Top up or add a payment method in the provider's console (for example OpenRouter or OpenAI), then try again.
"Provider is rate limited" (429)
You've hit the provider's rate limit. Wait a moment and use Retry. If it keeps happening, slow down or check your plan's limits with the provider.
Models & capabilities
Which models support images (vision)?
It depends on the model. Cordy tags models from the provider catalog (falling back to a bundled LiteLLM snapshot). If a model can't accept images, Cordy blocks image send before any request and shows "Choose a vision-capable model before sending images," with a Change model action. Pick a model tagged for vision to attach images.
Which models support extended thinking?
Only thinking-capable models. The reasoning-level control appears only for those and offers Off, Balanced, and Deep. Cordy drops a saved level when the active model lacks Thinking capability.
Can Cordy run tools / function calls?
Not yet. Tool / function calling is represented in the message format (the app can render tool-use and tool-result blocks) but is not executed in this release. Automatic multi-provider gateway and fallback routing are also future work — today each conversation uses exactly one provider and one model.
Costs & usage
Why does a cost show "≈"?
Some providers don't return token usage with a response. When that happens, Cordy estimates the token counts on-device and marks the resulting figures with a leading ≈ on the Settings → Token usage page. Prices come from the provider (when reported) or a bundled LiteLLM snapshot; when no price is known, the model shows —.
Are the in-app costs exact?
Treat them as estimates. Cost is computed from the price captured at completion time, and token counts may be locally estimated (≈). Always reconcile against your provider's own billing for the authoritative number.
Where do I see what I've spent?
Settings → Token usage shows totals plus per-model, per-provider, and per-day breakdowns.
Platform & availability
Is iOS available yet?
The published v0.5.0 baseline has meaningful Android evidence, but camera, share-in, real microphone, and TalkBack checks remained open. The repository records no completed iOS binary link, execution, or simulator/device smoke, and its old klib compile is stale after later source changes. Full detail is on Privacy & security.
Why don't I see the camera / photo / microphone buttons on iOS?
Those capture entry points are disabled in the current iOS dependency graph, so Cordy hides them. Android implements all three paths, with gallery image send verified on a device; camera, share-in, and real voice smoke remain open. iOS sharing/export is source-wired, but the repository records no runtime evidence.
Data & privacy
Does Cordy send my conversations anywhere?
Only your prompts, only to the provider you selected, only when you send a message. There is no Cordy backend, no account, no cloud sync, and no telemetry. See Privacy & security for the full story.
Where are my API keys stored?
In platform secure storage only—Android uses a Keystore-held AES-256-GCM key. iOS source uses a device-bound Keychain accessibility class, but the repository records no completed iOS runtime verification. Keys are never stored in the conversation database or application logs.
How do I wipe everything?
Settings → Erase all local data. It clears the database, preferences, stored keys, attachments, and caches from the device in one action, and reports honestly if any boundary fails. It does not touch the app binary or OS-level backups. See Privacy & security → one-tap erase.