Using UML Combined Fragments to Document API Error Paths Without Diagram Bloat

Most API sequence diagrams show the happy path and relegate error handling to prose bullets or a separate "failure modes" appendix. A developer implementing the client then has to mentally merge three documents to answer a simple question: what happens when the access token is expired but the refresh token is still valid? The useful takeaway is that UML 2.x combined fragments—alt, opt, loop, and break—let you place conditional branches, optional side effects, and bounded retries directly on the lifelines, so the contract stays in one diagram instead of scattering across your wiki.

Why separate error diagrams drift

When success and failure live in different diagrams, the common setup messages are duplicated. Change the authentication header format in the happy-path diagram, forget the error diagram, and the specification is now internally inconsistent. Combined fragments avoid that duplication by partitioning a single interaction with guards, so shared messages appear once and conditional logic stays visually attached to the flow it modifies.

The operators: alt, opt, loop, and break

A combined fragment is a rectangular region on a sequence diagram governed by an interaction operator. The four operators below cover the majority of API contract conditionals.

Operator	Guard syntax	Typical API use
alt	[valid token] / [invalid token]	Mutually exclusive success and failure responses
opt	[welcome email enabled]	Optional side effect after a primary message
loop	*[retry < 3]	Bounded polling or client-side retry
break	[fatal validation error]	Early exit from the enclosing interaction

The alt fragment partitions a sequence into mutually exclusive guards. An authentication endpoint can diverge between [valid credentials] and [invalid credentials] without duplicating the initial POST /login message. The opt fragment models a single conditional region—ideal for an optional side effect such as sending a welcome email only when a marketing flag is true. The loop fragment captures repeated polling or retry logic with explicit bounds like *[retry < 3], making the maximum attempt count visible rather than implied. The break fragment is often underused; it specifies an alternative scenario that exits the enclosing interaction, which is useful for circuit-breaker patterns or fatal validation errors that abort a transaction early.

A worked example: token validation with retry

Consider a three-lifeline diagram with Client, API Gateway, and Auth Service. The client posts credentials, the gateway validates the token, and the response determines the path.

1. Client → API Gateway: POST /login
2. API Gateway → Auth Service: validateToken(token)
3. alt [200 OK]
   • Auth Service → API Gateway: 200 {userId}
   • API Gateway → Client: 200 {session}
   • opt [profile incomplete]
     • API Gateway → Client: 302 /complete-profile
4. else [401 Unauthorized]
   • Auth Service → API Gateway: 401
   • API Gateway → Client: 401
   • loop [retry < 3]
     • Client → API Gateway: POST /refresh
   • break [refresh token expired]
     • API Gateway → Client: 403 Forbidden
     • Interaction terminates

This single diagram answers questions that would otherwise require three prose sections: what the success response looks like, when the profile redirect fires, how many refresh attempts are permitted, and what terminates the flow entirely.

Density limits and practical verification

The trade-off is diagram density. Deeply nested alt and loop fragments quickly become unreadable. A practical rule is to avoid nesting more than two levels deep; extract sub-scenarios into referenced interaction uses (sd ref) rather than stacking guards inside guards. Tool support varies as well: mainstream UML tools render combined fragments reliably, but round-trip engineering to code is rare, so these diagrams function best as human-readable specifications rather than executable artifacts.

Before publishing the contract, run four checks. First, ask a teammate to trace both the alt branches without verbal explanation; if they hesitate, the guards are ambiguous. Second, export the diagram to XMI and re-import it in a second UML tool to confirm that guards and fragment operators survive the round trip. Third, compare the modeled loop bounds against the actual retry policy in your service configuration to catch drift between documentation and implementation. Fourth, verify that any referenced interaction uses resolve to existing diagrams in your model repository.

UML 2.x combined fragments are stable, but check whether your tool targets UML 2.4, 2.5, or later when importing XMI, since interchange can drop custom stereotypes. Treat the diagram as a specification aid, not an exhaustive test oracle: combined fragments clarify control flow, but they do not replace concrete API schema definitions or contract tests.