Documentation
¶
Overview ¶
Package denial is the single client-error-envelope/v1 type for cost-bearing and entitlement denials. The schema lives in the workspace (public StackKits standards/client-error-envelope.v1.schema.json). Callers must not declare a parallel envelope; user_guidance is always an object.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( ErrInvalidEnvelope = errors.New("denial: envelope is not client-error-envelope/v1") ErrGuidanceObject = errors.New("denial: user_guidance must be an object") )
Functions ¶
This section is empty.
Types ¶
type Action ¶
type Action struct {
Kind ActionKind `json:"kind"`
ModelID string `json:"model_id,omitempty"`
ProviderID string `json:"provider_id,omitempty"`
EndpointID string `json:"endpoint_id,omitempty"`
}
Action is semantic: clients map it to their own trusted UI, never a served executable or arbitrary navigation URL. Validate checks the kind's parameters.
type ActionKind ¶
type ActionKind string
const ( ActionRetry ActionKind = "retry" ActionSignIn ActionKind = "sign_in" ActionSelectModel ActionKind = "select_model" ActionSelectFreeModel ActionKind = "select_free_model" ActionConfigureProvider ActionKind = "configure_provider" ActionUseProviderKey ActionKind = "use_provider_key" ActionUseModelEndpoint ActionKind = "use_model_endpoint" ActionManagePlan ActionKind = "manage_plan" ActionBuyAIBoost ActionKind = "buy_ai_boost" ActionContactSupport ActionKind = "contact_support" )
type Cause ¶
type Cause string
const ( CauseAuthentication Cause = "authentication" CauseAuthorization Cause = "authorization" CauseModelPolicy Cause = "model_policy" CauseFunding Cause = "funding" CauseCapacity Cause = "capacity" CauseConfiguration Cause = "configuration" CauseInfrastructure Cause = "infrastructure" CauseProvider Cause = "provider" CapabilityModelExecutions = "ai.model-executions" CapabilityAgentRuns = "ai.agent-runs" )
type Envelope ¶
type Envelope struct {
ErrorCode string `json:"error_code"`
ReasonCode string `json:"reason_code"`
RequestID string `json:"request_id,omitempty"`
Capability string `json:"capability,omitempty"`
ProviderID string `json:"provider_id,omitempty"`
RequiredFeatures []string `json:"required_features,omitempty"`
MissingFeatures []string `json:"missing_features,omitempty"`
Cause Cause `json:"cause,omitempty"`
RetryAfterMS *int64 `json:"retry_after_ms,omitempty"`
ResetAt string `json:"reset_at,omitempty"`
Actions []Action `json:"actions,omitempty"`
Retryable bool `json:"retryable"`
UserGuidance UserGuidance `json:"user_guidance"`
Remediation string `json:"remediation,omitempty"`
SupportContext map[string]any `json:"support_context,omitempty"`
}
Envelope is the machine-readable denial. Required fields match the workspace schema: error_code, reason_code, retryable, user_guidance.
func Parse ¶
Parse accepts the canonical envelope and the three running representations declared in workspace client-error-transport.v1.schema.json. Aliases are validated as their named transport, never admitted as canonical extensions.
func (Envelope) MarshalJSON ¶
MarshalJSON always writes user_guidance as an object.
type Localization ¶
type UserGuidance ¶
type UserGuidance struct {
Title string `json:"title"`
Body string `json:"body"`
NextSteps []string `json:"next_steps"`
Localization *Localization `json:"localization,omitempty"`
}
UserGuidance is the human-facing part of a denial. It is always a JSON object with title, body, and at least one next step.