Error Models: HTTP, Problem Details, and gRPC

Stage 2 compressed for lookup. Lesson 2 covers what a status code promises and lesson 3 covers the structured formats; this sheet is what to reach for while designing an error model, not while learning why it is contract.

Which document settles it

HTTP status codes worth being exact about

404 versus 403 is a design decision, not an accident: returning 404 to an unauthorised caller is how an API avoids confirming that a resource exists.

Retry-After

RFC 9110 section 10.2.3 defines the field for 503 and for any 3xx. RFC 6585 says a 429 may carry it. Nothing else is specified, so a client that only honours it on 503 is still conformant and a server that relies on more is not.

Retry-After = HTTP-date / delay-seconds

Retry-After: Fri, 31 Dec 1999 23:59:59 GMT
Retry-After: 120

Method safety and idempotency

Idempotency is a property of the method, from RFC 9110's method registry, not of the status code that came back.

POST being the only non-idempotent one in this set is why a timed-out create needs either an idempotency key the server deduplicates on, or a PUT with a client-supplied identifier.

RFC 9457 Problem Details

Media type application/problem+json, or application/problem+xml for the XML form in appendix B.

{
  "type": "https://api.example.com/errors/insufficient-funds",
  "title": "Insufficient funds",
  "status": 409,
  "detail": "Your balance is 30 and this transfer costs 50.",
  "instance": "/transfers/9f2c1a",
  "balance": 30,
  "shortfall": 20
}

Rules that make the format extensible rather than merely conventional:

• Anything beyond the five members is an extension member, and that is where machine-readable specifics belong. balance and shortfall above are extensions.
• A consumer must ignore extension members it does not recognise, which is what lets a problem type gain detail without breaking clients.
• A member whose value is the wrong type must be ignored, and processing continues as if it were absent.
• Prefer an absolute type URI. A relative one resolves against the document's base URI, so the same string under two resources identifies two different problem types.
• The type URI does not have to resolve, and a resolvable one is encouraged. Switching a non-resolvable identifier to a resolvable one later is a breaking change, because it is a new identity for the same problem.

gRPC status codes

Every RPC ends in a status: an integer code plus a string description. Codes and numbers from the gRPC guide; the HTTP column is the canonical mapping in google.rpc.Code.

The seven marked no are never produced by the gRPC libraries, only by user code. Seeing one tells you the application rejected the call rather than the transport failing, which is the fastest triage signal gRPC gives you for free.

The mapping is one-way and lossy. Three gRPC codes collapse onto 400 and two onto 409, so an HTTP status alone cannot reconstruct which gRPC code produced it. That is the argument for carrying a stable identifier of your own on both sides.

Retryable, retryable elsewhere, or not retryable

The gRPC guide gives an explicit rule for the three codes teams confuse most.

Denied, or not there

• Denied for an entire class of users, such as a gradual rollout or an undocumented allowlist: NOT_FOUND may be used.
• Denied for some users within a class, meaning ordinary access control: PERMISSION_DENIED must be used.
• PERMISSION_DENIED must not be used when a resource ran out, which is RESOURCE_EXHAUSTED, nor when the caller cannot be identified at all, which is UNAUTHENTICATED.
• PERMISSION_DENIED implies nothing about whether the request was valid or the entity exists.

One model across both transports

The wire formats cannot be identical. What travels across both is the identifier.

On the gRPC side the identifier rides in an error detail attached through google.rpc.Status, which is the counterpart to the type URI, not the status code itself.

Before shipping an error model

• Every error a client is expected to handle differently has its own stable identifier, and that identifier is documented.
• No client is expected to parse detail, a message string, or a status code alone to tell two errors apart.
• The retryable set is explicit, and the codes in it are the ones the specs say are retryable.
• A 429 or 503 that expects a retry says when, using Retry-After.
• Every non-idempotent operation a client might retry after a timeout has a deduplication mechanism.
• The identifiers mean the same thing on both transports, and the mapping between them is written down rather than inferred.

Sources

• RFC 9110: "HTTP Semantics", IETF
• RFC 6585: "Additional HTTP Status Codes", IETF
• RFC 9457: "Problem Details for HTTP APIs", IETF
• Docs: "Status Codes", gRPC
• google.rpc.Code, googleapis
• Resources