api-error-observability

API Error And Observability

Core Goal

Make failures understandable to users, clients, operators, and future agents. Every important error should answer: what happened, who is affected, can it be retried, and where is the evidence?

Error Contract

Use a stable error shape:

{
  "type": "https://docs.example.com/errors/quota-exceeded",
  "code": "quota_exceeded",
  "message": "Quota exceeded for this workspace.",
  "request_id": "req_123",
  "retryable": false,
  "details": {
    "limit": 1000,
    "window": "month"
  }
}

Expose safe messages to clients. Put sensitive internals only in logs.

HTTP Status Guidance

Status	Use For
400	invalid request shape
401	not authenticated
403	authenticated but not allowed
404	not found or intentionally hidden
409	conflict, version mismatch, duplicate invariant
422	semantic validation failure
429	rate limited
500	unhandled server error
503	temporary service unavailable

Do not return 200 with an error object for normal APIs.

Logging Rules

• Log structured fields, not only prose.
• Include request id, trace id, user id if safe, tenant id if safe, route, method, status, duration, and error code.
• Redact secrets and PII.
• Log at boundaries: request start/end, external calls, queue jobs, auth failures, and critical domain transitions.
• Avoid logging full request bodies by default.

Trace And Metrics

Minimum metrics:

• request count by route/status
• latency histogram by route
• error count by code
• dependency latency and failure rate
• queue lag if API enqueues work

Minimum tracing:

• inbound request span
• database query spans or summarized DB timing
• external HTTP calls
• queue publish/consume spans
• cache calls when they affect latency

SLO And Alerting

Alert on symptoms before causes:

• p95/p99 latency above SLO
• error rate above threshold
• dependency failure spike
• queue lag above threshold
• no traffic when traffic is expected