Backup keys & failover
A workspace can hold one key per provider, and Promptly uses them as an ordered chain: the Primary first, then each backup in turn. If the primary fails for a reason that points at the key itself, the next one takes over mid-request — the visitor gets their answer, and you find out from the card, not from a complaint.
Order is priority
The list on Settings → AI Keys is the failover order, top to bottom. The first card is badged Primary; the rest are Backup #1, Backup #2, and so on.
To reorder, click Set as primary on the credential you want first. It moves ahead of every other key; the previous primary becomes Backup #1. There's no drag-and-drop — promoting the one you want is the whole interaction.
🖼️ [Image] — Two credential cards, the first badged "Primary" and the second "Backup #1" with a "Set as primary" button.
Which keys are eligible
A key is only a failover candidate if:
- its status is Verified — Unverified, Invalid key, Out of credits, Provider down, and Disabled keys are all skipped; and
- for Chat and Planner, it also has Tool calling ✓.
Background jobs have the looser requirement, so a key that connects but can't call tools still serves as a background backup while being ignored for chat. See Model roles.
Because eligibility is per role, it's worth keeping at least two fully verified keys if uptime matters.
What triggers a failover
Only failures that say something about the credential's health:
- 401 / 403 → the key is bad → marked Invalid key
- 402, or a body mentioning insufficient quota / credit balance / billing → Out of credits
- 5xx, timeouts, connection failures → Provider down
When one of these happens, Promptly records the new status on that credential (that's what updates the card and raises the banner), then retries the same request on the next eligible key.
A plain 429 rate limit is not a failover trigger — being told to slow down doesn't mean the key is unhealthy, so the request fails rather than silently spending your backup provider's budget.
When every key fails
If the chain is exhausted, the conversation fails and the widget shows the temporary-unavailability message instead of an answer. The dashboard raises a red LLM key issue detected banner naming each unhealthy credential, with a Check keys button. See Key statuses and Troubleshooting keys.
Building a sensible chain
- Two different providers, not two models at one provider — an outage or a billing problem usually hits a whole account.
- Keep the backup's models verified, not just present. An unverified backup is not in the chain.
- After a failover fires, top up or fix the primary and click Verify key to put it back in rotation. Nothing restores it automatically.