Error Types

ClientError

type ClientError = engine.ClientError

Classified HTTP client error, extracted via errors.As.

Struct Fields

type ClientError struct {
    Type       ErrorType  // Error classification
    Message    string     // Error description
    Cause      error      // Underlying error
    URL        string     // Request URL (masked)
    Method     string     // HTTP method
    Attempts   int        // Number of attempts made
    StatusCode int        // HTTP status code (if applicable)
    Host       string     // Hostname (for circuit breaker use)
}

Field	Type	Description
Type	ErrorType	Error classification for switch statements
Message	string	Error description
Cause	error	Underlying error, accessible via Unwrap()
URL	string	Request URL (credentials masked)
Method	string	HTTP method (GET, POST, etc.)
Attempts	int	Number of attempts (including the first request)
StatusCode	int	HTTP status code (0 for non-HTTP errors)
Host	string	Request hostname

Methods

Method	Return	Description
Error()	string	Formatted as METHOD URL: Message: Cause (attempt N)
Code()	string	Readable error code, e.g. "NETWORK_ERROR", "TIMEOUT"
IsRetryable()	bool	Whether the error is retryable
Unwrap()	error	Unwraps the underlying error
WithType(t ErrorType)	*ClientError	Returns a copy with the error type set (does not modify original)

var clientErr *httpc.ClientError
if errors.As(err, &clientErr) {
    fmt.Println("Error type:", clientErr.Code())
    fmt.Println("Request URL:", clientErr.URL)
    fmt.Println("Retry attempts:", clientErr.Attempts)
    fmt.Println("Retryable:", clientErr.IsRetryable())
    fmt.Println("Underlying error:", clientErr.Unwrap())
}

ErrorType

type ErrorType = engine.ErrorType

Error classification enum.

Constant	Description	Retryable
ErrorTypeUnknown	Unknown/unclassified error	No
ErrorTypeNetwork	Network error (connection refused, connection reset, etc.)	Conditional
ErrorTypeTimeout	Request timeout	Conditional¹
ErrorTypeContextCanceled	Context canceled	No
ErrorTypeResponseRead	Response body read error	Conditional
ErrorTypeTransport	Transport layer error	Yes
ErrorTypeRetryExhausted	Retries exhausted	No
ErrorTypeTLS	TLS error	No
ErrorTypeCertificate	Certificate verification error	No
ErrorTypeDNS	DNS resolution error	Conditional
ErrorTypeValidation	Request validation error	No
ErrorTypeHTTP	HTTP layer error	Conditional

¹ Timeouts triggered by a context deadline (WithTimeout, TimeoutConfig.Request) are not retried; only transport-level timeouts (e.g. net.OpError timeout) are retried.

Type Checking

result, err := client.Get(url)
if err != nil {
    var clientErr *httpc.ClientError
    if errors.As(err, &clientErr) {
        switch clientErr.Type {
        case httpc.ErrorTypeTimeout:
            log.Println("Request timeout")
        case httpc.ErrorTypeNetwork:
            log.Println("Network error")
        case httpc.ErrorTypeTLS:
            log.Println("TLS error")
        case httpc.ErrorTypeCertificate:
            log.Println("Certificate verification failed")
        case httpc.ErrorTypeDNS:
            log.Println("DNS resolution failed")
        case httpc.ErrorTypeRetryExhausted:
            log.Println("Retries exhausted")
        case httpc.ErrorTypeContextCanceled:
            log.Println("Request canceled")
        case httpc.ErrorTypeValidation:
            log.Println("Request validation failed")
        }
    }
}

Error Variables

Configuration Errors

Variable	Description
ErrNilConfig	Configuration is nil
ErrInvalidTimeout	Invalid timeout value
ErrInvalidRetry	Invalid retry configuration
ErrInvalidConnection	Invalid connection configuration
ErrInvalidSecurity	Invalid security configuration
ErrInvalidMiddleware	Invalid middleware configuration

Request Errors

Variable	Description
ErrInvalidHeader	Header validation failed

Response Errors

Variable	Description
ErrResponseBodyEmpty	Response body is empty
ErrResponseBodyTooLarge	Response body exceeds size limit

File Errors

Variable	Description
ErrEmptyFilePath	File path is empty
ErrFileExists	File already exists

Client Errors

Variable	Description
ErrClientClosed	Client is closed

Variable Matching

if errors.Is(err, httpc.ErrClientClosed) {
    // Client is closed
}
if errors.Is(err, httpc.ErrResponseBodyEmpty) {
    // Response body is empty
}

See Also

• Error Handling - Complete error handling guide
• Constants and Types - BodyKind and other constants reference
• Retry and Fault Tolerance - Retry strategy guide