🤖 docs: scope the namespace deletion step and list the exact uncertain-create cases

docs/how-to/troubleshooting.md

@@ -170,7 +170,7 @@ A `list` in one namespace that contains no `CoderControlPlane` at all does not r
 
 The logs show which provider configuration the server used.
 
-## Aggregated reads return `multiple eligible CoderControlPlane ...`
+## Aggregated reads return `multiple eligible CoderControlPlane instances`
 
 The server expects one eligible control plane for each request scope. If more than one control plane is eligible, do one of these steps:
 
@@ -280,7 +280,7 @@ CAUTION: Delete the workspace in Coder before you remove the finalizer. Otherwis
 ## A namespace stays `Terminating`
 
 1. Tests in the namespace wait for their cleanup. List them with `kubectl get codertemplatetests -n <namespace>`, then see [A `CoderTemplateTest` does not finish deleting](#a-codertemplatetest-does-not-finish-deleting).
-2. If the namespace condition `NamespaceDeletionContentFailure` is `True`, read its message. It contains the error that the aggregated API returned when the namespace controller listed its resources, for example a `503` or a `400`. For what each error means, see [Namespaces without a Coder backend](../reference/aggregated-api-behavior.md#namespaces-without-a-coder-backend) and [Aggregated reads return `ServiceUnavailable`](#aggregated-reads-return-serviceunavailable). If a `CoderControlPlane` is still in the namespace, check its finalizers, for example `coder.com/workspace-rbac-cleanup`, and the controller logs.
+2. If the namespace condition `NamespaceDeletionContentFailure` is `True`, read its message. Kubernetes sets this condition when any API fails while the namespace controller removes the resources of the namespace. If the message names `aggregation.coder.com`, it contains the error that the aggregated API returned when the namespace controller listed its resources, for example a `503` or a `400`. For a `503`, see [Namespaces without a Coder backend](../reference/aggregated-api-behavior.md#namespaces-without-a-coder-backend) and [Aggregated reads return `ServiceUnavailable`](#aggregated-reads-return-serviceunavailable). For a `400` that says `multiple eligible CoderControlPlane instances`, see [Aggregated reads return `multiple eligible CoderControlPlane instances`](#aggregated-reads-return-multiple-eligible-codercontrolplane-instances). If the message names another API, examine that API instead. If a `CoderControlPlane` is still in the namespace, check its finalizers, for example `coder.com/workspace-rbac-cleanup`, and the controller logs.
 
     ```bash
     kubectl get namespace <namespace> -o jsonpath='{range .status.conditions[*]}{.type}={.status} {.message}{"\n"}{end}'

docs/reference/aggregated-api-behavior.md

@@ -17,7 +17,7 @@ The aggregated API server serves `coderworkspaces`, `codertemplates` and `codert
 | [Template versions](#template-versions) | Read-only: `get` and `list`, no watch. Reads never download template source. |
 | [Promote a template version](#promote-a-template-version) | `codertemplates/<name>/promote` (`create`) makes a version active. A rollback promotes an older version. It needs its own RBAC grant. `dryRun=All` previews it. An unconfirmed result returns `503`, and a concurrent change returns `409`. |
 | [Template builds](#template-builds) | Create and update with `spec.files` wait until Coder completes the import. The full request must complete within 34 seconds. |
-| [Coder timeouts](#coder-timeouts) | A Coder call that runs out of time returns `504` on every resource. Most broken `2xx` answers to a create also return `504`. After a `504` on a write, re-read before you retry. |
+| [Coder timeouts](#coder-timeouts) | A Coder call that runs out of time returns `504` on every resource. A create that gets a broken `2xx` answer returns `504` or `500`. After a `504` on a write, re-read before you retry. |
 | [Workspace build log](#workspace-build-log) | `coderworkspaces/log` returns the latest build log as text. It needs its own RBAC grant and has fixed size, time, and concurrency limits. |
 | [Start and stop](#start-and-stop) | `coderworkspaces/start` and `coderworkspaces/stop` start or stop a workspace. Each needs its own RBAC grant. A repeated request does not queue a second build while one is active. |
 
@@ -225,7 +225,12 @@ A Coder call that runs out of time returns `504 Gateway Timeout` on every aggreg
 - the request deadline ends first (see [The 34-second write budget](#the-34-second-write-budget), the [log limits](#workspace-build-log), and the [start and stop budget](#time-limit-and-retries)), or
 - Coder itself answers `504`.
 
-A create of a workspace or a template also returns `504` when the answer to the create request has a `2xx` status, but is not the answer that Coder sends. For example, a proxy in front of Coder sends an HTML page, an empty body, or a status other than `201`. Coder can have created the object, so the message says that the result is uncertain. Some broken `2xx` answers still return `500`: a `200` with malformed JSON, and a connection that breaks while the server reads the answer. Coder can have created the object in these cases too, so re-read before you retry.
+A create of a workspace or a template can also get a broken `2xx` answer, for example from a proxy in front of Coder. Coder can have created the object. The server returns `504` for some of these answers and `500` for others:
+
+- `504`, with a message that says that the result is uncertain. Examples are a `201` with an HTML page, an empty body, invalid JSON, or a JSON array, and a `200` with an HTML page or with the JSON of Coder.
+- `500`. Examples are a `200` with the type `application/json` and invalid JSON or a JSON array, a `201` with `{}` or `null`, and a connection that breaks while the server reads the answer.
+
+After a `504` or a `500` on a create, re-read the object before you retry.
 
 The message does not include the Coder URL.