Platform & API Product Engineering · Lesson 03

Designing your API error model

Your error contract is not an afterthought — it is the part of your API that determines how quickly an integration partner can diagnose and recover from a problem at 2 a.m. A badly designed error model makes every bug an escalation; a well-designed one lets clients self-serve.

Why error design matters as much as success design

Most API design effort goes into the happy path: the right resource shape, sensible field names, a clean pagination cursor. The error path gets an afterthought — a string message and a 400. But the error path is where integration problems live. When a payment fails, a webhook bounces, or a validation check rejects a request, the quality of your error response determines whether the developer can fix it in minutes or files a support ticket.

Think of the error response as a patient chart at a hospital. The HTTP status code is the triage category on the door — "urgent" or "stable". The machine-readable error code is the diagnosis — precise and stable so a computer can route it. The human message is the doctor's note — readable but not something software should parse, because next month the wording might change. The request ID is the chart number that lets support pull the full record. Strip any of these layers and the chart becomes useless to half the people who need it.

The error envelope

A well-designed error body wraps a single error object at the top level. The outer key keeps success and error shapes clearly separated — a client can check if ("error" in body) to know which branch to take, rather than peeking at status codes already captured at the transport layer.

// Full error envelope — canonical structure
{
  "error": {
    // MACHINE layer — clients branch on these; they are CONTRACT-STABLE
    "type":       "invalid_request_error",  // top-level category
    "code":       "amount_too_small",       // stable, specific sub-code

    // HUMAN layer — readable prose; NEVER parse this string
    "message":    "Amount must be at least 50 cents (USD).",

    // FIELD layer — for validation errors; which param is wrong?
    "param":      "amount",

    // SUPPORT layer — trace it in your logs; paste it in a ticket
    "request_id": "req_9GqX2mHk7fP3n",
    "doc_url":    "https://docs.example.com/errors/amount_too_small"
  }
}

The three layers: status, code, message

The error contract has three distinct consumers. HTTP status codes are consumed by infrastructure — proxies, load balancers, CDNs, monitoring systems. Machine-readable codes are consumed by client code — the if code == "card_declined" branch. Human messages are consumed by people — the developer reading the log at 2 a.m. Mixing these layers causes problems: if your client branches on message text, a copy edit to fix a typo breaks your integration.

The three layers explained

Mapping domain errors to HTTP status codes

HTTP status codes are the transport signal. They must be chosen based on what the error means to the protocol, not just what the error means to your domain. Many teams default to 400 for every client error, which is too coarse. A misconfigured rate limiter that silently returns 400 instead of 429 prevents every well-behaved SDK from triggering its automatic retry logic.

The "200 with an error body" anti-pattern

A pervasive pattern in older APIs: every response returns HTTP 200, and success vs. failure is communicated only in the body with a status: "error" field. GraphQL uses a variant of this. The motivation is usually "it simplifies the client" — you always get a 200, so you check the body every time. This trades one kind of complexity for three worse kinds.

Error taxonomy: client, transient, and business

Beyond individual status codes, there is a higher-level taxonomy that determines the correct action a client should take. Getting this taxonomy right in your documentation — and in your response body — is what enables fully automated recovery in client SDKs.

Signalling retryability

Documenting retryability in your developer docs is necessary but not sufficient — well-designed SDKs need to know it at runtime. The cleanest approach is an explicit field in the error body:

{
  "error": {
    "type":      "rate_limit_error",
    "code":      "rate_limit_exceeded",
    "message":   "Too many requests. Please slow down.",
    "retryable": true,         // machine-readable retry signal
    "retry_after": 23          // seconds to wait (also in Retry-After header)
  }
}

For business errors that require user action before retrying, use a dedicated value — not just false — so the SDK can distinguish "don't retry" from "retry after user fixes something":

{
  "error": {
    "type":      "card_error",
    "code":      "card_declined",
    "decline_code": "insufficient_funds",  // Stripe's second-level code
    "message":   "Your card has insufficient funds.",
    "retryable": "after_user_action"      // not a bool; distinguishes the case
  }
}

Field-level validation errors

Validation errors deserve special treatment because a single request can violate multiple constraints at once. A user submitting a form should get all the errors in one round trip, not one at a time. The pattern is to promote the error body to contain a list of per-field problems:

// 422 — multiple validation failures in one response
{
  "error": {
    "type":    "invalid_request_error",
    "code":    "validation_failed",
    "message": "The request contains invalid parameters.",
    "details": [
      {
        "param":   "amount",
        "code":    "amount_too_small",
        "message": "Must be at least 50 (cents)."
      },
      {
        "param":   "currency",
        "code":    "unsupported_currency",
        "message": "'XYZ' is not a supported currency code."
      }
    ],
    "request_id": "req_9GqX2mHk7fP3n"
  }
}

The top-level code is validation_failed (machine-readable, stable). The per-field codes in details are also stable. The message at each level is human-readable prose. A web client can walk details and highlight each problematic field; a CLI tool can print them all at once.

Partial and batch failures

A batch endpoint accepts many items in one request. Some may succeed; others may fail. Returning 400 or 422 implies the whole batch failed. Returning 200 implies all items succeeded. Neither is right for partial success. The correct status is 207 Multi-Status, borrowed from WebDAV and adopted widely for batch APIs. Each item in the response carries its own status code and, if it failed, its own error object:

// POST /v1/charges/batch — 207 Multi-Status
{
  "results": [
    {
      "index":  0,
      "status": 200,
      "id":     "ch_abc"
    },
    {
      "index":  1,
      "status": 422,
      "error":  {
        "type":    "invalid_request_error",
        "code":    "amount_too_small",
        "message": "Amount must be at least 50 cents.",
        "param":   "amount"
      }
    },
    {
      "index":  2,
      "status": 200,
      "id":     "ch_xyz"
    }
  ]
}

The request_id: linking errors to logs

The request_id is a unique identifier generated by your API server at the start of processing — before any business logic runs. It should appear in every response, successful or not. It must appear in every error. Its purpose is to allow a developer or support agent to paste one string into a logging query and retrieve the complete, correlated trace for that request.

Generate it as a prefixed opaque token — req_ followed by a URL-safe base62 string. Prefix the ID so it is immediately recognisable in a paste. Log it at the start and end of the request lifecycle, including every downstream call made during that request. Set it as the X-Request-Id response header as well, so clients who can't read the body (e.g. a load balancer doing health checks) can still correlate.

Standards: RFC 9457, Google, and gRPC

The API industry has not converged on a single error format, but three influential standards are worth knowing. None of them is inherently better — your choice depends on your ecosystem and how much you want to align with existing tooling.

Under the hood: how it actually works end-to-end

Trace what happens when a payment API receives a request with an invalid amount. The error model is not a separate layer — it runs through the entire stack from input parsing to the bytes on the wire.

1. Request arrives at the API gateway. The gateway performs authentication (checking the API key against the database). If authentication fails, the gateway returns 401 immediately — before the request even reaches the application server. The request_id is generated here and attached to every downstream log entry for this request.
2. Request deserialization. The framework parses the JSON body. If the JSON is malformed (syntax error), the framework returns 400 Bad Request before your code runs. The error body at this level typically says "failed to parse body" — it does not have a domain error code because no domain logic ran.
3. Schema validation middleware. Your validation layer checks the parsed body against the request schema. It collects all validation violations (not just the first). If any violations exist, it constructs the details array and returns 422. The request_id is included in the body, having been propagated through a thread-local or request context.
4. Domain logic. Validation passed; the business logic runs. A card charge is attempted. The payment processor declines: insufficient_funds. The application maps this to the error envelope: type=card_error, code=card_declined, decline_code=insufficient_funds. HTTP status: 402.
5. Error middleware assembles the response. A top-level error handler catches any unhandled exception (e.g. a database connection failure). It logs the full stack trace internally and returns a sanitised 500 with only the request_id in the body — no internal details. This is the firewall between your internal implementation and what the client sees.
6. Response serialisation. The error object is serialised to JSON. Content-Type is set to application/json (or application/problem+json if using RFC 9457). Status line, headers, and body are written to the socket.

Design trade-offs

By the numbers

Consider a payment API processing 5,000 charges/min (modeled). Historical data shows a 2% card decline rate and a 0.5% validation error rate. The error model choices have measurable operational impact.

How real platforms do it

Error model design is where you see the starkest differences between platforms. The choices reflect the platform's maturity, their support volume, and how much they invest in developer experience.

How to debug & inspect it

When an API client reports an error, the fastest path to resolution is the request_id. Everything else — the error code, the status code, the message — narrows down the cause. The request_id is the key that opens the server log.

Trace an error end-to-end with curl

Symptom → cause → fix

Sources & further reading

• RFC 9457 — Problem Details for HTTP APIs
• Google AIP-193 — Errors
• Google Cloud API Design Guide — Errors
• Stripe API error object reference
• Twilio error dictionary
• gRPC status codes
• GitHub REST API best practices — error handling
• Lesson 07 — HTTP (status codes, headers)
• Reliability 05 — Retries & backoff
• Debug 02 — Reading error responses