CONCEPT Cited by 1 source

Problem vs Error distinction¶

Definition¶

In Zalando's 2021 GraphQL error-modeling discipline, Problem and Error are distinct, non-overlapping vocabulary:

Error — anything appearing in the response.errors array of the GraphQL response envelope, optionally carrying extensions.code.
Problem — an error modelled inside the schema as a GraphQL type, typically a member of a union ...Result = Success | ...Problem.

The split exists because GraphQL has already claimed the name error for its response envelope (response.errors), so using that name for schema types would confuse every contributor and every reader of the schema. The name Problem is borrowed from RFC 7807 — Problem Details for HTTP API:

"Since the name error is already taken by the GraphQL language (response.errors), it would be confusing to name our error types in Schema as Error. As we did before to look for inspirations, there is a well-defined concept in RFC 7807 - Problem details for HTTP API. So, we will call all our errors in Schema as Problems and, as it has always been, all other errors as errors."

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

What the split lets you say¶

Because the names don't overlap, a schema reviewer can write a rule like:

"A *Problem type may appear only in a ...Result union."
"A query or mutation that can fail only with non-Customer-actionable failures must not return a *Problem type."

And a documentation reader can immediately tell whether the author is talking about the response envelope or the schema.

Shape in the wild¶

union RegisterResult = RegisterSuccess | RegisterProblem

type RegisterSuccess { id: ID!  email: String! }

type RegisterProblem {
  title: String!                         # translated
  invalidInputs: [RegisterInvalidInput]
}

The word Problem is a load-bearing naming convention, not an implementation detail.

Relationship to action-taker classification¶

The Problem/Error split is the naming layer on top of error action-taker classification:

Customer-actionable → schema-modelled as Problem.
Developer-actionable or bug → response.errors as Error.

Why this is more than naming¶

The split is also a semantic distinction:

Errors participate in GraphQL's default null-propagation semantics: one Error in a non-nullable field bubbles up the tree.
Problems are schema branches: they don't propagate; the client must explicitly spread both union members (... on Success { ... } ... on Problem { ... }).

The choice of where to put an error is therefore the choice of what null-propagation behaviour the field should have.

Seen in¶

sources/2021-04-12-zalando-modeling-errors-in-graphql — where the naming discipline is established.