Recover from AI credit balance errors without losing work
Distinguish insufficient funding from expired authorization and unknown outcomes, then restore the user's work before offering another paid attempt.
A balance error should interrupt generation, not erase the work that made generation possible. If someone spends ten minutes preparing a brief, sending them back to a blank form after a failed payment check is a product bug, even when the billing response is correct.
For an app offering AI Pass, provider-key BYOK, or its own credits, recovery begins by identifying which funding route failed. AI Pass is a wallet-funded OAuth option, not a provider key. Its balance is separate from credits your app sells and from a provider's billing account.
Save a recovery packet before dispatch
Before the paid action starts, save the draft using your app's existing persistence. Include the input version, selected model, action settings, funding route, and a local operation reference. Store uploaded-file references while respecting their retention and expiry rules.
Do not put OAuth tokens or provider keys in this packet. It is a way to recover user work, not a credential backup. The AI Pass integration guide explains the separation between the host app and its AI connection.
If saving fails, say so before sending the generation request. For sensitive material that your app intentionally does not persist, provide a local export or another explicit recovery option. "Your draft is safe" is a claim about your implementation, not a reassuring default string.
Give each failure a different next step
Map actual SDK or API responses into app states. The names below are proposed internal states, not official AI Pass error codes. Check the SDK documentation or REST reference for the contract used by your integration.
| App state | What the app knows | Message and next action |
|---|---|---|
| Funding blocked | A definitive response says the selected balance cannot fund this request | Keep the draft; offer balance review or another funding method |
| Connection expired | Authorization is no longer usable | Ask the user to reconnect; retain settings |
| Provider limit reached | The BYOK route reports a provider billing or quota restriction | Link to that provider's account guidance; do not request an AI Pass top-up |
| Outcome unknown | The connection failed after dispatch and completion is unconfirmed | Show checking status; do not automatically generate again |
| Partial output | Some output arrived but the action did not finish cleanly | Preserve the partial result separately from the original draft |
| Completed | The result is durably stored | Open the saved result instead of repeating the request |
A generic "Add credits" modal is wrong for most of these rows. It can also be wrong for a temporary service failure that has nothing to do with balance.
Returning from a balance review
Keep the editor route and operation reference available while the user reviews their wallet. When they return, restore the draft and refresh the connection or balance information supported by your integration. Do not treat a visible balance as a reservation: other activity may change it before the next request.
Show a review step with the original input and selected funding source. The user may have changed their mind while away. A top-up or reconnection should not silently restart a paid action.
Use copy such as: "Your brief is ready. Review the funding method, then choose Generate to try again." If the earlier attempt has an unknown outcome, replace that invitation with status checking and support options until you can explain the risk of another request.
Switching to app credits or BYOK also needs an explicit choice. Do not make the app's own balance a hidden fallback when the wallet cannot pay.
A support template that preserves useful evidence
Provide a copyable report with fields the app can safely populate:
Subject: Generation could not finish
App operation reference: [reference]
Time and timezone: [time]
Funding method: [AI Pass wallet / provider key / app credits]
Feature and model: [selection]
Last visible state: [state]
Draft restored: [yes / no]
Output received: [none / partial / complete]
What I tried afterward: [user description]
Please check the operation status before advising another paid attempt.
Tell users not to include keys, tokens, full payment details, or private document text. Support should already be able to find the relevant app record from the operation reference. A screenshot should be optional and reviewed for sensitive content.
Test the return journey
Use controlled error responses to exercise each row, including closing the funding window and refreshing the editor. Confirm that input formatting, file references, and model settings survive as promised. Test unknown outcomes separately from insufficient balance.
The acceptance test is specific: the user can recover their prepared work, understand what happened, and choose the next paid action without being nudged into a duplicate charge.