Documentation
¶
Overview ¶
Package errors defines custom error types for the SDK.
Package errors provides a single, unified custom error type for the CortexCloud SDK, designed to encapsulate all error information, whether originating from an upstream API or from internal SDK operations.
Index ¶
- Constants
- func AsCortexCloudSdkError(err error, target **CortexCloudSdkError) bool
- func IsCortexCloudSdkError(err error) bool
- type CortexCloudAPIError
- type CortexCloudAPIErrorContext
- type CortexCloudAPIErrorData
- type CortexCloudAPIErrorDetail
- type CortexCloudAPIErrorDetails
- type CortexCloudAPIErrorExtra
- type CortexCloudAPIErrorMetadata
- type CortexCloudAPIErrorParams
- type CortexCloudAPIErrorReply
- type CortexCloudSdkError
- func NewBadRequest(code, message string, details []CortexCloudSdkErrorDetail) *CortexCloudSdkError
- func NewConflict(code, message string, details []CortexCloudSdkErrorDetail) *CortexCloudSdkError
- func NewCortexCloudSdkError(code string, message string, details []CortexCloudSdkErrorDetail, ...) *CortexCloudSdkError
- func NewForbidden(code, message string) *CortexCloudSdkError
- func NewInternalSDKError(code, message string, err error) *CortexCloudSdkError
- func NewInternalServerError(code, message string, err error) *CortexCloudSdkError
- func NewNotFound(code, message string) *CortexCloudSdkError
- func NewPreRequestValidationError(details []CortexCloudSdkErrorDetail, err error) *CortexCloudSdkError
- func NewServiceUnavailable(code, message string) *CortexCloudSdkError
- func NewUnauthorized(code, message string) *CortexCloudSdkError
- func (e CortexCloudSdkError) DetailsToJSON() (string, error)
- func (e CortexCloudSdkError) DetailsToPrettyJSON() (string, error)
- func (e *CortexCloudSdkError) Error() string
- func (e CortexCloudSdkError) ToJSON() (string, error)
- func (e CortexCloudSdkError) ToPrettyJSON() (string, error)
- func (e *CortexCloudSdkError) Unwrap() error
- type CortexCloudSdkErrorDetail
- func NewInvalidEnumValidationErrorDetail(err error, location, fieldName string, value any, enums []string) CortexCloudSdkErrorDetail
- func NewMinimumNumberOfValuesValidationErrorDetail(err error, location, fieldName string, expected string, actual int) CortexCloudSdkErrorDetail
- func NewRequiredValidationErrorDetail(err error, location, fieldName string) CortexCloudSdkErrorDetail
- func NewUnexpectedValidationErrorDetail(err error, location string) CortexCloudSdkErrorDetail
- func NewUnknownValidationTagErrorDetail(err error, location, tag string) CortexCloudSdkErrorDetail
- type ErrorExtraField
Constants ¶
const ( // Error Codes/Messages CodePreRequestValidationFailure = "PreRequestArgumentValidationFailure" MsgPreRequestValidationFailure = "Pre-request argument validation failed. See details for more information." // Error Detail Codes/Messages DetailCodeUnexpectedValidationError = "UnexpectedValiadationError" DetailMsgUnexpectedValidationError = "Encountered unexpected error during validation. See \"Error\" field for more information." DetailCodeUnknownValidationTag = "UnknownValidationTag" DetailMsgUnknownValidationTag = "" /* 140-byte string literal not displayed */ DetailCodeMissingRequiredValue = "MissingRequiredValue" DetailMsgMissingRequiredValue = "\"%s\" is a required value." DetailCodeMinimumNumberOfValues = "MinimumNumberOfValues" DetailMsgMinimumNumberOfValues = "Field \"%s\" must have at least %s value(s) provided (recieved %d)." DetailCodeInvalidEnumValue = "InvalidEnumValue" DetailMsgInvalidEnumValue = "Invalid %s value \"%v\" - expected one of: %s" CodeAPIResponseParsingFailure = "" CodeSDKInitializationFailure = "" CodeRequestSerializationFailure = "" CodeURLConstructionFailure = "" CodeContextCancellation = "" CodeHTTPRequestCreationFailure = "" CodeAuthenticationHeaderGenerationFailure = "" CodeNetworkError = "" CodeNoResponseReceived = "" CodeResponseBodyReadFailure = "" CodeResponseDeserializationFailure = "" )
Variables ¶
This section is empty.
Functions ¶
func AsCortexCloudSdkError ¶
func AsCortexCloudSdkError(err error, target **CortexCloudSdkError) bool
AsCortexCloudSdkError attempts to cast the given error to *CortexCloudSdkError. It returns true if the conversion is successful, and the sdkErr pointer will point to the CortexCloudSdkError instance. This is a wrapper around errors.As.
func IsCortexCloudSdkError ¶
IsCortexCloudSdkError checks if the given error is of type *CortexCloudSdkError. It uses errors.As to safely perform the type assertion.
Types ¶
type CortexCloudAPIError ¶
type CortexCloudAPIError struct {
Reply *CortexCloudAPIErrorReply `json:"reply,omitempty"`
Data *CortexCloudAPIErrorData `json:"data,omitempty"`
Code *string `json:"errorCode,omitempty"`
Message *string `json:"message,omitempty"`
Details *CortexCloudAPIErrorDetails `json:"details,omitempty"`
// Fields for root-level error format (e.g. CloudSec)
ErrCode *int `json:"err_code,omitempty"`
ErrMsg *string `json:"err_msg,omitempty"`
Metadata *CortexCloudAPIErrorMetadata `json:"metadata,omitempty"`
}
func NewCortexCloudAPIError ¶
func NewCortexCloudAPIError(code string, message string, details CortexCloudAPIErrorDetails) CortexCloudAPIError
func (CortexCloudAPIError) Error ¶
func (e CortexCloudAPIError) Error() string
func (CortexCloudAPIError) HasContent ¶
func (e CortexCloudAPIError) HasContent() bool
HasContent reports whether at least one of the known error fields was populated during JSON unmarshaling. When json.Unmarshal succeeds on valid JSON that uses none of the expected keys (e.g. `{"error":"msg"}`), every pointer field stays nil and HasContent returns false. Callers should treat this as "unrecognised error format" and fall back to including the raw HTTP response body so the user is never shown an empty error.
func (CortexCloudAPIError) ToBuiltin ¶
func (e CortexCloudAPIError) ToBuiltin() error
ToBuiltin converts the CortexCloudAPIError to a standard Go error. It ensures that the error message contains all relevant details.
type CortexCloudAPIErrorData ¶
type CortexCloudAPIErrorData struct {
Message string `json:"err_msg"`
Metadata *CortexCloudAPIErrorMetadata `json:"metadata,omitempty"`
}
type CortexCloudAPIErrorDetail ¶
type CortexCloudAPIErrorDetail struct {
Type string `json:"type"`
Location []any `json:"loc"`
Message string `json:"msg"`
Input any `json:"input"`
Context CortexCloudAPIErrorContext `json:"ctx"`
}
type CortexCloudAPIErrorDetails ¶
type CortexCloudAPIErrorDetails struct {
// Params is set when the "params" key is present (legacy shape).
Params CortexCloudAPIErrorParams `json:"-"`
// Fields is the parsed per-field validation map. Each entry is
// "field path" -> { message: "..." }. Empty when no per-field details
// were returned.
Fields map[string]CortexCloudAPIErrorParams `json:"-"`
}
CortexCloudAPIErrorDetails handles both the legacy "params" shape and the AppSec-style per-field map shape returned by HTTP 422 ValidateError responses.
Legacy "params" shape:
"details": { "params": { "message": "..." } }
AppSec per-field map shape (e.g. policy CREATE/UPDATE 422):
"details": {
"policy.triggers.ciImage": { "message": "'ciImage' is required" },
"policy.triggers.imageRegistry": { "message": "'imageRegistry' is required" }
}
Fields populated by UnmarshalJSON depend on which shape was returned.
func (CortexCloudAPIErrorDetails) MarshalJSON ¶
func (d CortexCloudAPIErrorDetails) MarshalJSON() ([]byte, error)
MarshalJSON implements custom JSON marshaling that round-trips both shapes.
func (*CortexCloudAPIErrorDetails) UnmarshalJSON ¶
func (d *CortexCloudAPIErrorDetails) UnmarshalJSON(data []byte) error
UnmarshalJSON implements custom JSON unmarshaling that accepts:
- {"params": {"message": "..."}} -> Params
- {"<fieldPath>": {"message": "..."}, ...} -> Fields
- mixed (params + arbitrary other keys) -> both
type CortexCloudAPIErrorExtra ¶
type CortexCloudAPIErrorExtra struct {
Type string `json:"type,omitempty"`
Location []any `json:"loc,omitempty"`
Message string `json:"msg,omitempty"`
MessageFull string `json:"message,omitempty"`
Field any `json:"field,omitempty"`
Input any `json:"input,omitempty"`
Context CortexCloudAPIErrorContext `json:"ctx,omitempty"`
}
type CortexCloudAPIErrorMetadata ¶
type CortexCloudAPIErrorMetadata struct {
Code int `json:"err_code"`
Extra ErrorExtraField `json:"err_extra"`
}
type CortexCloudAPIErrorParams ¶
type CortexCloudAPIErrorParams struct {
Message string `json:"message"`
}
type CortexCloudAPIErrorReply ¶
type CortexCloudAPIErrorReply struct {
Code int `json:"err_code"`
Message string `json:"err_msg"`
Extra ErrorExtraField `json:"err_extra"`
}
type CortexCloudSdkError ¶
type CortexCloudSdkError struct {
Code string `json:"code"` // A unique, machine-readable error code (e.g., "INVALID_ARGUMENT", "UNAUTHORIZED", "SDK_INIT_FAILED").
Message string `json:"message"` // A human-readable message describing the error.
Details []CortexCloudSdkErrorDetail `json:"details"` // Optional, additional context or validation errors.
InternalErrorsCount int `json:"internal_errors_count"` // Total number of internal errors returned.
HTTPStatus *int `json:"http_status"` // The HTTP status code associated with this error. This value is nil for internal errors.
Err error `json:"underlying_error"` // The underlying Go error returned by the validation module.
}
CortexCloudSdkError represents a structured error within the CortexCloud SDK. It can represent errors returned by an upstream API (with HTTPStatus populated) or internal SDK errors (with HTTPStatus as nil).
func NewBadRequest ¶
func NewBadRequest(code, message string, details []CortexCloudSdkErrorDetail) *CortexCloudSdkError
NewBadRequest creates a CortexCloudSdkError for HTTP 400 Bad Request. Use this for client-side input validation errors from an API.
func NewConflict ¶
func NewConflict(code, message string, details []CortexCloudSdkErrorDetail) *CortexCloudSdkError
NewConflict creates a CortexCloudSdkError for HTTP 409 Conflict. Use this when an API request conflicts with the current state of the target resource.
func NewCortexCloudSdkError ¶
func NewCortexCloudSdkError( code string, message string, details []CortexCloudSdkErrorDetail, httpStatus *int, err error, ) *CortexCloudSdkError
NewCortexCloudSdkError creates a new CortexCloudSdkError. Use this as the primary constructor for all SDK errors.
Parameters:
code: A machine-readable error code. message: A human-readable message. details: Optional slice of CortexCloudSdkErrorDetail for more context. httpStatus: Optional HTTP status code (pass nil for internal SDK errors). err: Optional underlying Go error to wrap.
func NewForbidden ¶
func NewForbidden(code, message string) *CortexCloudSdkError
NewForbidden creates a CortexCloudSdkError for HTTP 403 Forbidden. Use this when the client is authenticated but does not have permission to access the resource via API.
func NewInternalSDKError ¶
func NewInternalSDKError(code, message string, err error) *CortexCloudSdkError
NewInternalSDKError creates a CortexCloudSdkError for errors originating purely within the SDK's logic. These errors will have HTTPStatus as nil.
func NewInternalServerError ¶
func NewInternalServerError(code, message string, err error) *CortexCloudSdkError
NewInternalServerError creates a CortexCloudSdkError for HTTP 500 Internal Server Error. Use this for unexpected server-side errors from an API, potentially wrapping an underlying Go error.
func NewNotFound ¶
func NewNotFound(code, message string) *CortexCloudSdkError
NewNotFound creates a CortexCloudSdkError for HTTP 404 Not Found. Use this when the requested API resource does not exist.
func NewPreRequestValidationError ¶
func NewPreRequestValidationError(details []CortexCloudSdkErrorDetail, err error) *CortexCloudSdkError
func NewServiceUnavailable ¶
func NewServiceUnavailable(code, message string) *CortexCloudSdkError
NewServiceUnavailable creates a CortexCloudSdkError for HTTP 503 Service Unavailable. Use this when the upstream API server is not ready to handle the request.
func NewUnauthorized ¶
func NewUnauthorized(code, message string) *CortexCloudSdkError
NewUnauthorized creates a CortexCloudSdkError for HTTP 401 Unauthorized. Use this when authentication credentials are missing or invalid for API calls.
func (CortexCloudSdkError) DetailsToJSON ¶
func (e CortexCloudSdkError) DetailsToJSON() (string, error)
DetailsToJSON serializes the CortexCloudSdkError.Details into a JSON string without indentation. It excludes the `Err` field as it's marked with `json:"-"`.
func (CortexCloudSdkError) DetailsToPrettyJSON ¶
func (e CortexCloudSdkError) DetailsToPrettyJSON() (string, error)
DetailsToPrettyJSON serializes the CortexCloudSdkErrors.Details into a JSON string with indentation. It excludes the `Err` field.
func (*CortexCloudSdkError) Error ¶
func (e *CortexCloudSdkError) Error() string
Error implements the error interface for CortexCloudSdkError. It returns a formatted string representation of the error.
func (CortexCloudSdkError) ToJSON ¶
func (e CortexCloudSdkError) ToJSON() (string, error)
ToJSON serializes the CortexCloudSdkError into a JSON string without indentation. It excludes the `Err` field as it's marked with `json:"-"`.
func (CortexCloudSdkError) ToPrettyJSON ¶
func (e CortexCloudSdkError) ToPrettyJSON() (string, error)
ToPrettyJSON serializes the CortexCloudSdkError into a JSON string with indentation. It excludes the `Err` field.
func (*CortexCloudSdkError) Unwrap ¶
func (e *CortexCloudSdkError) Unwrap() error
Unwrap returns the underlying Go error, allowing for error chain inspection using errors.Unwrap from the standard library.
type CortexCloudSdkErrorDetail ¶
type CortexCloudSdkErrorDetail struct {
Location string `json:"location"` // The path or field where the error occurred (e.g., "body.user_id").
Code string `json:"code"` // A specific code for this detail (e.g., "INVALID_FORMAT").
Message string `json:"message"` // A human-readable message for this specific detail.
Error error `json:"underlying_error"` // The underlying Go error.
}
CortexCloudSdkErrorDetail provides granular context about specific error instances, often used for validation errors or specific problem details within the main error.
func NewInvalidEnumValidationErrorDetail ¶
func NewInvalidEnumValidationErrorDetail(err error, location, fieldName string, value any, enums []string) CortexCloudSdkErrorDetail
func NewMinimumNumberOfValuesValidationErrorDetail ¶
func NewMinimumNumberOfValuesValidationErrorDetail(err error, location, fieldName string, expected string, actual int) CortexCloudSdkErrorDetail
func NewRequiredValidationErrorDetail ¶
func NewRequiredValidationErrorDetail(err error, location, fieldName string) CortexCloudSdkErrorDetail
func NewUnexpectedValidationErrorDetail ¶
func NewUnexpectedValidationErrorDetail(err error, location string) CortexCloudSdkErrorDetail
func NewUnknownValidationTagErrorDetail ¶
func NewUnknownValidationTagErrorDetail(err error, location, tag string) CortexCloudSdkErrorDetail
type ErrorExtraField ¶
type ErrorExtraField struct {
// contains filtered or unexported fields
}
ErrorExtraField handles both string and array formats for err_extra field
func (ErrorExtraField) MarshalJSON ¶
func (e ErrorExtraField) MarshalJSON() ([]byte, error)
MarshalJSON implements custom JSON marshaling
func (*ErrorExtraField) UnmarshalJSON ¶
func (e *ErrorExtraField) UnmarshalJSON(data []byte) error
UnmarshalJSON implements custom JSON unmarshaling to handle both string and array formats
func (ErrorExtraField) Values ¶
func (e ErrorExtraField) Values() []CortexCloudAPIErrorExtra
Values returns the underlying slice of error extra objects