apierror

type APIError struct {
	StatusCode int
	Type       ErrorType
	// Code is the stable, opaque error code (E#####).
	Code string
	// Name is a human-readable slug for logs; paired with Code, never replaces it.
	Name string
	// Message is the human-readable description.
	Message string
	// DocURL links to the documentation for this Code.
	DocURL string
	// RequestID correlates with the X-Request-Id response header.
	RequestID string
	// Param is the offending field, when applicable.
	Param string
	// VendorCode is a verbatim code from a downstream system (SMTP reply, decline).
	VendorCode string
	// Remediation is a human-readable next step to resolve this error, when a
	// recovery is known (ADR-0073).
	Remediation string
	// Next lists the operations that resolve this error, in the order to try them.
	Next []ErrorNextAction
	// UnmetGates lists the verification requirements blocking this action, each
	// with the flow that resolves it. Present only when an action is blocked
	// pending verification.
	UnmetGates []UnmetGate
}

type ConnectionError struct{ Err error }

type ErrorDetail struct {
	// Param is the dotted field path, e.g. "to[0]", "subject".
	Param string `json:"param"`
	// Message is what is wrong with this field.
	Message string `json:"message"`
}

type ErrorNextAction struct {
	// Operation is the operationId of the follow-up operation that resolves this error.
	Operation string `json:"operation"`
	// Description is a short human-readable label for the recovery step.
	Description string `json:"description,omitempty"`
	// Scope is the permission scope the recovery operation requires, when it is scoped.
	Scope string `json:"scope,omitempty"`
}

type ErrorType string

type RateLimitError struct {
	*APIError
	RetryAfter time.Duration
}

type TimeoutError struct{ Timeout time.Duration }

type UnmetGate struct {
	// Slug is the stable identifier for the verification requirement.
	Slug string `json:"slug"`
	// Name is the human-readable name of the verification requirement.
	Name string `json:"name"`
	// Status is the requirement's current state.
	Status string `json:"status"`
	// RemediationKind is how to resolve this requirement.
	RemediationKind string `json:"remediation_kind"`
}

type ValidationError struct {
	*APIError
	Details []ErrorDetail
}

type WebhookVerificationError struct{ Reason string }