What Happens When AI Generation Fails After Credits Are Deducted?

An AI generation request often has to consume credits before external work can begin. That creates an awkward window: the user has paid, but the provider has not yet returned a usable result.

NimBuild handles that window with an explicit compensation object.

The Compensation Pattern

The documented flow is:

const compensation = createCreditCompensation({
  userId,
  amount: creditsNeeded,
  reason: "credit_adjustment_refund",
  referenceId,
});

try {
  await doExternalWork();
  compensation.settle();
} catch (error) {
  await compensation.compensate();
  throw error;
}

The sequence is intentional:

1. Check affordability.
2. Deduct credits in the database transaction.
3. Prepare compensation.
4. Call the provider.
5. Settle when provider work succeeds.
6. Refund through the ledger when it fails.

The compensation path does not edit a balance in place. It creates an auditable refund event.

The docs example uses the generic credit_adjustment_refund reason to demonstrate the helper. For the AI tool workflow, NimBuild also documents the more specific ai_generation_refund reason, which is what makes AI provider compensation distinguishable from other credit adjustments.

What Counts as Failure?

For a production AI workflow, failure is broader than an HTTP 500:

• provider timeout
• authentication or quota error
• invalid provider response
• missing required output fields
• unsafe or unusable content
• storage failure that prevents a required asset from being read

Define which failures are refundable before launch. NimBuild’s compensation pattern is designed for operations where credits have already been deducted and external work then fails.

Why the Ledger Reason Matters

NimBuild uses ai_generation for consumption and ai_generation_refund for provider-failure compensation. Those names let support distinguish:

• a normal usage charge
• a failed generation refund
• a manual support adjustment
• a generic product refund

Without those distinctions, every balance restoration looks alike. That makes fraud checks, unit economics, and provider reliability reporting harder.

Generation History Is Part of the Promise

The AI tool workspace records generation history. A user should be able to review what they requested and what happened. For failures, that history may show an error; for successes, it preserves the workflow result.

History also creates operational context. An occasional timeout is different from a regional provider outage affecting many customers.

Avoid Two Tempting Shortcuts

Shortcut 1: Deduct Only After the Provider Succeeds

This avoids refunds, but it allows users to start unlimited external work without a guaranteed balance. It also creates race conditions when two requests check the same balance concurrently.

Shortcut 2: Catch Every Error and Silently Restore the Balance

This feels user-friendly, but it loses accounting context. Later, nobody can tell whether the refund was caused by provider failure, support policy, or a bug.

NimBuild’s approach is stricter: deduct atomically, then compensate explicitly.

Questions to Test in Your Own Workflow

1. Does an unaffordable request start provider work?
2. Are two concurrent requests prevented from spending the same credits?
3. Is compensation idempotent if retry logic runs twice?
4. Does a timeout refund exactly the deducted amount?
5. Is the failed operation visible in history?
6. Can admin ledger review show the original charge and refund?
7. Do retry and refund use the same stable reference?

User Experience After Failure

Tell the user what happened and what was restored:

• The generation failed.
• The deducted credits were returned.
• They can retry.
• Support can review the event if it repeats.

Do not hide the failure while leaving credits missing. Trust in a paid AI product depends on visible reconciliation.

Compensation turns provider failure from a balance bug into an auditable customer recovery flow.