中文
devexamples
← Workflows

阅读中文版本

API Error Format Standardization Workflow

Define an error schema with code, message, and details, map status codes consistently, document it, and migrate endpoints to it over time.

intermediate~90 minapierror-handlingconsistency

Objective

Make API errors consistent so clients can handle failures with one code path.

Environment

  • An API with several error-handling styles
  • A documented error schema target

Steps

1. Define the canonical error object

Define the canonical error object with machine-readable code and safe message.

Expected state: Errors have a stable shape.

2. Map domain conditions to HTTP statuses

Map domain conditions to HTTP statuses and document each mapping.

Expected state: Status semantics are consistent.

3. Add a request reference id

Add a request reference id for support correlation.

Expected state: Failures can be traced.

4. Migrate inconsistent endpoints with a compatibility

Migrate inconsistent endpoints with a compatibility period.

Expected state: Clients are not broken abruptly.

Decision points

Change status codes for consistency?

  • Yes with deprecation
  • Keep old codes

Changing codes breaks clients; introduce the new shape behind a version and deprecate the old.

Expose validation details?

  • Field-level, sanitized
  • Full internal detail

Field-level details help clients; full internal detail leaks implementation.

Expected outcome

All endpoints return errors in one schema with consistent status codes and traceable reference ids.

Verification

Confirm a representative set of failures across endpoints produce the canonical shape and that no stack traces leak.

Cleanup

Publish the error catalog and track endpoints still to migrate.

Overview

Make API errors consistent so clients can handle failures with one code path. Confirm a representative set of failures across endpoints produce the canonical shape and that no stack traces leak.

Steps

  1. Define the canonical error object with machine-readable code and safe message. Expected state: Errors have a stable shape.
  2. Map domain conditions to HTTP statuses and document each mapping. Expected state: Status semantics are consistent.
  3. Add a request reference id for support correlation. Expected state: Failures can be traced.
  4. Migrate inconsistent endpoints with a compatibility period. Expected state: Clients are not broken abruptly.
{
  "error": {
    "code": "validation_failed",
    "message": "Email is invalid",
    "details": [{ "field": "email", "issue": "invalid_format" }],
    "ref": "req_01J..."
  }
}

Verification

  • All endpoints return errors in one schema with consistent status codes and traceable reference ids.

Decision points

  • Change status codes for consistency? Options: Yes with deprecation; Keep old codes. Recommended: Changing codes breaks clients; introduce the new shape behind a version and deprecate the old.
  • Expose validation details? Options: Field-level, sanitized; Full internal detail. Recommended: Field-level details help clients; full internal detail leaks implementation.