Response & Telemetry

This is the typical pattern for structured errors. Exact fields may vary by endpoint version.

Example (illustrative) error shape

• No internal stack traces are exposed.

• Error messages remain actionable.

• A request identifier is always present for debugging.

Errors are standardized at the gateway boundary:

Error behavior

• Domain service returns a structured payload to the gateway.

• Gateway applies the public response contract.

• Gateway attaches telemetry metadata such as:

  • request identifier

  • timestamps

  • (optionally) processing duration

Response path

Responses are consistent across the platform. Telemetry is emitted for every request, success or failure.

{
  "error": {
    "code": "rate_limited",
    "message": "Request quota exceeded.",
    "request_id": "req_01J...",
    "details": {
      "scope": "api_key",
      "window": "rolling"
    }
  }
}

If a request fails intermittently, retry with backoff. If it fails consistently, treat it as a deterministic client error.