Skip to main content

Error Model contracted

Every API error should use the standard error envelope with a stable machine code and correlation id. Clients and SDKs should branch on HTTP status and catalog code, not on human-readable messages.

Envelope​

{
  "code": "allocation_not_found",
  "message": "The requested allocation does not exist or is not accessible.",
  "correlation_id": "01HXYZ...",
  "details": {}
}

Rules​

  • Codes are stable once shipped.
  • New codes are additive.
  • validation_error includes field-level details.
  • Implementations must not invent codes outside the catalog.
  • 5xx paths must classify upstream dependency failure versus local defect.
Canonical sources