Foundationv1Platform contracts

Errors and correlation IDs

Return an actionable error without exposing stacks, SQL, secrets, or another tenant's data.

Last reviewed: July 16, 2026
Audience: backend · mobile · integration
Contract state: Foundation

Error envelope

Clients need a stable machine code, a localizable message, and an opaque correlation_id for support. Business logic must never depend on message text.

{\n  "error": {\n    "code": "scope_denied",\n    "message": "The requested scope is not available.",\n    "correlation_id": "<opaque-id>",\n    "retryable": false\n  }\n}

Actionable classification

Separate validation, authentication, authorization, conflict, rate limit, transient dependency, and internal failures. Include retryable and retry_after only when accurate.

Error privacy

Responses must not expose stack traces, table names, queries, local paths, secrets, or the existence of a resource outside tenant scope.