Errors
JSON shape
Many routes return code, title, category, why, optional recovery, retryable, details (see resolveAuthorizedPrincipal, resolveAuthorizedOrg).
The TypeScript SDK parses error bodies with externalDiagnosticWireSchema in core/http.ts, falling back to a generic internal_error / Request failed when the body does not match.
HTTP status
- 400 — bad request (missing
organizationId, validation) - 401 — invalid bearer / API key
- 403 — wrong org, missing scope, or API key on unsupported route
- 500 — server errors from orchestration
Legacy fields
Some handlers still attach error / message strings alongside structured fields for compatibility.