Failure Handling

Handle payment failures, retries, and error propagation safely.

advanced5 days

Public lesson — sign in to track progress on this roadmap.

Learning objectives

Categorize permanent vs transient payment failures
Retry with updated pathfinding knowledge
Avoid unsafe refund UX mistakes

study // plan

Lessons are primers. Start with Step 1 (required reading) when present, then follow the numbered steps in the article. Depth comes from primary sources, labs, reflection, and evidence.

Research on Bitcoin Search

Step 1 // Required reading

Complete these before the numbered steps in the lesson body. Links are listed here once — not repeated below.

boltBOLT4 failure messages

Reflection prompts

Explain Failure Handling to a teammate without jargon - what problem does it solve?
What would break in production if you misunderstood Failure Handling?
Which BOLT (or implementation doc) is the source of truth for this topic, and what did you verify there?

Lab // Failure triage

Complete Steps 2–3. Trigger or simulate a failed payment on Polar (wrong amount route, closed channel, or expired invoice). Classify transient vs permanent and write your retry policy.

evidence required

Failure evidence (error text, Polar UI, or simulated scenario notes)
Classification: transient vs permanent + retry yes/no
Idempotency note (payment hash / key) for merchant UX
Link to BOLT4 failures section you used

Most Lightning payments fail at least once before succeeding. Good software treats failure as information, not as a dead end.

Complete Step 1 // Required reading in the study plan above, then continue here.

Step 2 — Core idea: transient vs permanent

Naive “try once and show error” UX makes Lightning feel broken. Smart retries with fee budgets make it feel instant.

Class	Examples	Action
Transient	Imbalance, unknown liquidity, tight fees	Update scores / route; retry within budget
Permanent	Invalid invoice, unknown peer, exhausted expiry	Stop; surface clear error

Loading diagram…

Parse errors, retry when sensible, stop when permanent.

Done when: You can triage one failure into transient vs permanent without guessing.

Step 3 — Triage a failure (lab)

Cause or simulate a failure. Classify it. State retry policy and idempotency key.

Done when: Lab evidence (failure + classification + idempotency + source) is complete.

Next lesson

Lightning Attack Surface — congestion, probing, watchtowers, and CVE lessons.

Discussion

prevMultipath Payments nextLightning Attack Surface

Step 2 — Core idea: transient vs permanent

Naive “try once and show error” UX makes Lightning feel broken. Smart retries with fee budgets make it feel instant.

Class	Examples	Action
Transient	Imbalance, unknown liquidity, tight fees	Update scores / route; retry within budget
Permanent	Invalid invoice, unknown peer, exhausted expiry	Stop; surface clear error

Loading diagram…

Parse errors, retry when sensible, stop when permanent.

Done when: You can triage one failure into transient vs permanent without guessing.

Failure Handling

Learning objectives

Step 1 // Required reading

Reflection prompts

Lab // Failure triage

How to study this lesson

Step 2 — Core idea: transient vs permanent

Step 3 — Triage a failure (lab)

Next lesson

further reading

Discussion

Failure Handling

Learning objectives

Step 1 // Required reading

Reflection prompts

Lab // Failure triage

How to study this lesson

Step 2 — Core idea: transient vs permanent

Step 3 — Triage a failure (lab)

Next lesson

further reading

Discussion