What causes "API error: nil response" in micro/go-micro?

Check and handle the transport error from the HTTP call before treating the response as valid — a nil response usually accompanies a non-nil error

micro/go-micro · error

API error: nil response

Error message

API error: nil response

What it means

NewHTTPError builds an HTTPError from an *http.Response, but if the response pointer is nil there is no status, header, or body to expose. Rather than panicking on a nil dereference, it returns this plain error indicating the API call produced no response at all (e.g. transport failure, client error, or a bug passing nil).

Source

Thrown at ai/retry.go:57

}

func (e *HTTPError) StatusCode() int {
	if e == nil {
		return 0
	}
	return e.Code
}

func (e *HTTPError) RetryAfter() time.Duration {
	if e == nil {
		return 0
	}
	return parseRetryAfter(e.Header.Get("Retry-After"), time.Now())
}

func NewHTTPError(resp *http.Response, body []byte) error {
	if resp == nil {
		return errors.New("API error: nil response")
	}
	return &HTTPError{Status: resp.Status, Code: resp.StatusCode, Body: string(body), Header: resp.Header.Clone()}
}

func parseRetryAfter(value string, now time.Time) time.Duration {
	value = strings.TrimSpace(value)
	if value == "" {
		return 0
	}
	if seconds, err := strconv.Atoi(value); err == nil {
		if seconds <= 0 {
			return 0
		}
		return time.Duration(seconds) * time.Second
	}
	when, err := http.ParseTime(value)
	if err != nil {
		return 0

View on GitHub (pinned to 24529f1404)

Solutions

Check and handle the transport error from the HTTP call before treating the response as valid — a nil response usually accompanies a non-nil error
Ensure any custom http.Client/Transport/RoundTripper never returns (nil, nil)
Verify network connectivity, proxy settings, and that the request actually reached the server

Example fix

// before
resp, _ := client.Do(req)
return NewHTTPError(resp, body)
// after
resp, err := client.Do(req)
if err != nil {
    return fmt.Errorf("request failed: %w", err)
}
if resp == nil {
    return errors.New("API error: nil response")
}

Defensive patterns

Strategy: try-catch

Validate before calling

resp, err := client.Do(req)
if err != nil { return fmt.Errorf("transport: %w", err) }
if resp == nil { return errors.New("no response from API") }

Type guard

func hasResponse(resp *http.Response) bool { return resp != nil }

Try / catch

err := doCall()
var httpErr *ai.HTTPError
if err != nil && !strings.Contains(err.Error(), "nil response") {
    if errors.As(err, &httpErr) { /* handle status/retry-after */ }
}

Prevention

Never discard the error from http.Client.Do; nil response almost always accompanies an error
Ensure custom RoundTrippers return (response, error) correctly — never (nil, nil)
Handle ctx cancellation and network failures distinctly from HTTP status errors

When it happens

Trigger: callAPI or Stream completing with resp == nil (connection failure before a response, or an error path passing nil into NewHTTPError).

Common situations: Network/DNS failures or context cancellation causing http.Client.Do to return nil response with a non-nil error; custom transports returning (nil, nil); mis-wired HTTP clients.

Related errors

AI-assisted analysis of micro/go-micro@24529f1404 (2026-09-01). Data as JSON: /api/errors/f17272391891abbe. Report an issue: GitHub.