1. Question
A B2B data API serves thousands of developer teams. After a release, support tickets increasingly say that requests fail without explaining how to fix them. Engineering wants to expose more internal logs, while sales asks for custom error text for every customer. As the product manager, design an actionable API error experience without breaking existing clients.
2. Constraints and clarifications
- Separate client-input, authentication and authorization, rate-limit, dependency, and internal-service failures; do not collapse every failure into one 500.
- Make the response serve machine handling, developer diagnosis, and end-user presentation without conflating their needs.
- Existing SDKs and log formats cannot all change immediately, so the plan must support old clients and gradual migration.
- Never return sensitive stacks, tokens, user data, or internal topology directly to callers.
3. Product diagnosis framework
Split the problem into three questions: what happened, who can fix it, and what should happen next. An error response needs a stable machine-readable code, a safe human summary, optional structured details, and a support correlation ID; docs and SDKs map the code to a fix. Product analysis should track recovery-after-error rate, repeated retries, time from failure to success, support tickets by error class, and version distribution, not just total failure rate.
4. Reference solution
errorResponse:
status: canonicalStatusCode
code: stableProductErrorCode
message: safeHumanSummary
details:
reason: machineActionableReason
fieldViolations: optionalFieldErrors
retryAfter: optionalDelay
requestId: supportCorrelationId
docsUrl: versionedFixGuide
clientFlow(error):
classify(error.status, error.code)
if retryable: backoffAndRetry(error.details.retryAfter)
else if fieldError: highlightFields(error.details.fieldViolations)
else: showDocsAndRequestId(error.docsUrl, error.requestId)Define a small set of stable canonical status codes, then use product error codes for actionable causes. Put field violations, retry timing, and documentation links in structured details. The console shows repair steps by code, while SDKs map errors to catchable types and preserve the original code. The service records complete diagnostics internally but returns only a safe summary and correlation ID.
5. Trade-offs and rollout strategy
Finer error codes make guidance more precise but raise compatibility and documentation costs. Start with high-volume errors that developers can fix, then add details for smaller classes; do not create a custom protocol per tenant. New fields should be backward compatible. Once a code’s meaning is public, keep it stable: old clients continue receiving the old format while newer SDKs opt into structured details. Partial-failure responses deserve caution because they add client branches; introduce them only when a batch API has a clear need.
6. Verification and observability
- Sample support tickets and call logs, labeling each failure as diagnosable, fixable, and retried unnecessarily or not.
- Write contract tests for auth, field validation, rate limits, dependency timeouts, and unknown failures, checking status, code, and docs URL.
- Gradually roll out the new format and compare recovery rate, repeated retries, ticket volume, and SDK exception-capture rate.
- Monitor unknown codes, old-client share, documentation-click-to-success conversion, and sensitive-field leakage in error responses.
7. Common mistakes
- Exposing more logs or stacks without giving callers a stable code and a repair action.
- Encoding all business meaning in HTTP status so clients must parse strings.
- Putting internal exceptions, tokens, or complete request parameters into a supposedly friendly message.
- Renaming or deleting codes in one release and breaking old SDKs during upgrade.
8. Interview scoring points
Classifies errors by repair responsibility
The candidate should separate input, permission, rate-limit, dependency, and internal failures and state the caller action and service responsibility for each.
Designs a stable and safe error model
The answer should include machine-readable codes, safe summaries, structured details, correlation IDs, and versioned docs without exposing internals.
Connects experience to product metrics
The candidate should use recovery rate, repeated retries, time to fix, tickets, and version distribution rather than failure rate alone.
Plans a compatible migration
The candidate should explain old-format compatibility, gradual SDK adoption, rollout and rollback criteria, and when not to introduce a complex partial-failure protocol.