PATTERN Cited by 1 source

Error extensions-code for developer-actionable errors¶

Pattern¶

For every failure mode whose action-taker is the Developer (front-end engineer / client code) — not the Customer — model the failure as an entry in response.errors carrying a stable, parseable extensions.code string. The client switches on the code, not the message.

Shape of a single error:

{
  "message": "Not Found",
  "path": ["product"],
  "extensions": { "code": "NOT_FOUND" }
}

Runtime / internal errors may skip the code entirely — the client's default behaviour (retry, show error page) applies to anything uncoded.

What counts as "developer-actionable"¶

The decision is inherited from concepts/error-action-taker-classification:

Failure	Code	Front-end response
Resource Not Found	`NOT_FOUND`	render 404 page
Unauthorized / not logged in	`NOT_AUTHORIZED`	show login dialog; navigate to login
Forbidden / missing permission	`FORBIDDEN`	render access-denied UI
Rate-limited	`RATE_LIMITED`	back off + retry with jitter
Runtime / Internal Server Error	(none — or `INTERNAL_`)	generic error UI + retry

The list is illustrative, not canonical — each organisation establishes its own code catalogue. What's canonical is the shape: extensions.code as a machine-readable switch.

Why not schema types for these¶

Zalando's discipline is explicit that developer-actionable failures should not become schema Problem types. The reasons:

Error propagation. These failures often need to propagate up a deeply nested query to a nullable ancestor; GraphQL's default null-propagation semantics does the right thing. Schema Problem types don't propagate.
Query ergonomics. Wrapping every field in ... on Success | ... on Error at every hierarchy level is what Zalando calls the "hammer and nails" failure mode. Keep schema types for the narrow Customer-actionable case.
Bug-class errors can't go in the schema. Runtime exceptions and internal infrastructure failures represent bugs, not domain states. Putting them in the schema would encode bug shape into the API contract.

(Source: sources/2021-04-12-zalando-modeling-errors-in-graphql)

Stability discipline¶

Because codes aren't in the schema — and therefore not covered by schema review, codegen, or introspection — the organisation has to add the discipline by convention:

Centralise the set of valid codes in a shared catalogue (a proto enum, a constants file, or a shared markdown catalogue).
Treat codes as a versioned API contract: adding is safe, renaming or removing is a breaking change.
Document expected client behaviour per code.
Don't encode variable data in the code string — variable detail goes in message or in other extensions fields.

Without this, you hit the schema discoverability gap at full force.

Pairs with¶

patterns/problem-type-for-customer-actionable-errors — the other arm of Zalando's discipline, used for the narrow Customer-actionable case.
patterns/result-union-type-for-mutation-outcome — the schema shape that pattern rides on.

Seen in¶

sources/2021-04-12-zalando-modeling-errors-in-graphql — the canonical source for the code / Problem split.