Kubernetes API Errors — 4xx and 5xx Explained

What the API server actually returns and why: 401 versus 403, when 403 is really an admission webhook, 409 on optimistic concurrency, 410 Gone on expired watches, 422 on validation, 429 with Retry-After from API Priority and Fairness, and the 5xx family including etcd timeouts. Each with the retry strategy that belongs with it.

Overview

Every interaction with Kubernetes is an HTTP call to the API server, so every failure arrives as an HTTP status code. Reading them correctly is the difference between "RBAC is broken" and "my controller has a stale cache", and those two have nothing in common.

The codes are not decorative. Kubernetes maps a specific internal reason onto each one — Unauthorized, Forbidden, Conflict, Gone, Invalid, TooManyRequests — and the response body carries a Status object with that reason and a human message. When you get an error from kubectl, the message you see is that Status.message field. Reading the code *and* the reason tells you which subsystem rejected you: authentication, authorization, admission, validation, concurrency control, or flow control.

Two distinctions cause most of the confusion in practice. First, 401 and 403 are different subsystems: 401 means the API server could not work out who you are, 403 means it knows exactly who you are and you are not allowed. Second, 403 is overloaded: RBAC denials and admission-webhook denials both return 403, and telling them apart is a matter of reading the message, not the code.

The other thing worth internalising early: several of these are *normal*. A 409 on a controller's update is expected under concurrent writes and the correct response is to re-read and retry, not to alert. A 410 on a watch is expected after etcd compaction and the correct response is to re-list. Treating routine codes as incidents is a common source of noise.

Sign up free to read the full topic

More DevOps topics

Start free on Cariara · Coding problems · System design studio