What causes "http request failure,status: %d" in AlistGo/alist?

Retry after a delay — the condition is usually transient (that is why it is wrapped in errNeedRetry).

http request failure,status: %d

Error message

http request failure,status: %d

What it means

Produced in the chunk response handler when the FIRST chunk (id 0) gets an HTTP status in the retryable set (429 TooManyRequests, 502, 503, 504). The first chunk gates the whole request, so it is wrapped in errNeedRetry with a 200ms pause, letting the outer loop re-establish the connection. Note the 'default' branch returns the raw err — the message only appears for those four statuses.

Source

Thrown at internal/net/request.go:414

	resp, err := d.cfg.HttpClient(d.ctx, params)
	if err != nil {
		if resp == nil {
			return 0, err
		}
		if resp.StatusCode == http.StatusRequestedRangeNotSatisfiable {
			return 0, err
		}
		if ch.id == 0 { //第1个任务 有限的重试，超过重试就会结束请求
			switch resp.StatusCode {
			default:
				return 0, err
			case http.StatusTooManyRequests:
			case http.StatusBadGateway:
			case http.StatusServiceUnavailable:
			case http.StatusGatewayTimeout:
			}
			<-time.After(time.Millisecond * 200)
			return 0, &errNeedRetry{err: fmt.Errorf("http request failure,status: %d", resp.StatusCode)}
		}

		// 来到这 说明第1个分片下载 连接成功了
		// 后续分片仅在限流/网关类错误时当超载处理，其余错误（如链接过期 403）直接失败
		switch resp.StatusCode {
		case http.StatusTooManyRequests, http.StatusBadGateway, http.StatusServiceUnavailable, http.StatusGatewayTimeout:
		default:
			return 0, err
		}
		log.Debugf("err chunk_%d, try downloading:%v", ch.id, err)

		d.m.Lock()
		isCancelConcurrency := ch.newConcurrency
		if d.concurrency > 0 { // 取消剩余的并发任务
			// 用于计算实际的并发数
			d.concurrency = -d.concurrency
			isCancelConcurrency = true
		}

View on GitHub (pinned to 843d9dc814)

Solutions

Retry after a delay — the condition is usually transient (that is why it is wrapped in errNeedRetry).
Lower download concurrency to avoid tripping rate limits.
If persistent, verify the remote service is healthy and the auth/URL has not expired.
Check the status code in the message to distinguish throttling (429) from gateway failures (502/503/504).

Defensive patterns

Strategy: retry

Type guard

var retryable *errNeedRetry
if errors.As(err, &retryable) { /* retryable */ }

Try / catch

n, err := d.downloadChunk(...)
if e, ok := err.(*errNeedRetry); ok {
    log.Warnf("retryable: %v", e)
    continue // outer loop already sleeps 200ms for chunk 0
}

Prevention

Honor errNeedRetry as retryable instead of failing the transfer.
Add jitter to retries when many clients share the same rate-limited endpoint.
Monitor which status dominates (429 vs 502/503/504) to pick the right fix.

When it happens

Trigger: Initial ranged GET for chunk 0 answered with 429/502/503/504 (throttling or gateway problems); repeated until the caller's retry budget is exhausted.

Common situations: Remote drive throttling new connections; frps/CDN gateway hiccup; service briefly down for maintenance; too many simultaneous download sessions from one IP.

Related errors

AI-assisted analysis of AlistGo/alist@843d9dc814 (2026-08-15). Data as JSON: /api/errors/5389c4c7fc0263e3. Report an issue: GitHub.