From b177ed459154374809bdc71c265d2d2d2ebc4688 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 29 Jul 2026 11:13:49 +0000 Subject: [PATCH] API-09 / API-11: correct the connection-status enum and complete the error table MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two docs-vs-code discrepancies from the remediation ledger, each verified against the control-plane source and by an independent adversarial check. API-09 (medium): the MCP page listed six connection statuses; three (`completed`, `error`, `expired`) do not exist. The real status is a closed four-value enum — `pending`, `propagating`, `live`, `failed` (services/control-plane/internal/model/model.go:116-119, asserted by status_test.go:59). Corrected content/mcp/overview.mdx to the four real values. API-11 (medium): the error-code table documented neither `forbidden` (403), `conflict` (409), nor `rate_limited` (429), though the handlers return all three. Added them to content/reference.mdx and content/api-reference/index.mdx. `quota_exceeded`, `ProviderAuthenticationError`, and `InvalidNameservers` — the other three the finding named — were already present from earlier work. Only codes/values that exist in the Go code were added; nothing invented. The OpenAPI enum already listed the correct four statuses, so check-openapi-sync stays green and no spec change was needed. Site builds clean (npm run build). API-03, API-08 and API-14 from the same cluster were checked and found already correct in these docs (12-attempt durable-outbox retries, twelve MCP tools, and all eight SDK window events respectively) — no change needed, verified not assumed. Claude-Session: https://claude.ai/code/session_01YFw2Aya3Vn1W3saDPs8XRY --- content/api-reference/index.mdx | 10 +++++++--- content/mcp/overview.mdx | 2 +- content/reference.mdx | 3 +++ 3 files changed, 11 insertions(+), 4 deletions(-) diff --git a/content/api-reference/index.mdx b/content/api-reference/index.mdx index 3fbf1b6..f46719f 100644 --- a/content/api-reference/index.mdx +++ b/content/api-reference/index.mdx @@ -43,12 +43,16 @@ Every error is the same shape: ``` `code` is a stable machine string. The generic codes are `invalid_request`, -`unauthorized`, `not_found`, `service_unavailable`, and `internal_error`. A few -connect-flow failures carry a distinct, branchable code instead of a generic one -so an integration can react specifically: +`unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, +`service_unavailable`, and `internal_error`. A few connect-flow failures carry a +distinct, branchable code instead of a generic one so an integration can react +specifically: | `code` | HTTP | Meaning | | --- | --- | --- | +| `forbidden` | 403 | Authenticated, but not permitted to perform this action. | +| `conflict` | 409 | The request conflicts with the resource's current state. | +| `rate_limited` | 429 | Too many requests — back off and retry. | | `quota_exceeded` | 402 | The plan's monthly quota is used up. Only `free` is hard-capped, and only where `BILLING_ENFORCE_QUOTA` is on (the hosted service currently runs meter-only, so nothing is refused today) — no paid tier is ever refused; see [Plans & quotas](/docs/billing/plans-and-quotas#overage). | | `InvalidNameservers` | 422 | The domain has no usable nameserver delegation, so its DNS provider can't be determined. | | `ProviderAuthenticationError` | 422 | The end-user's DNS provider rejected the authorization or credential. | diff --git a/content/mcp/overview.mdx b/content/mcp/overview.mdx index c4e9663..7c59b01 100644 --- a/content/mcp/overview.mdx +++ b/content/mcp/overview.mdx @@ -29,7 +29,7 @@ agent can never inject them. | `generate-domain-suggestions` | `{ keywords, limit? }` | Return available-to-register suggestions for a set of keywords (default 5, min 5, max 20), each priced; the cheapest is marked the top pick. | | `create-domain-order` | `{ domain }` | Start a registration/purchase through the resolved registrar. Enterprise/direct registrars return an `orderId`; sharing registrars return a checkout `link` + `jobId` to poll. | | `connect-domain` | `{ domain }` | Start a guided DNS-configuration flow for a domain the user already owns. Returns a `link` for the user and a `jobId` to poll. Never writes DNS directly. | -| `check-connection-status` | `{ jobId }` | Read the live status of a connection job. Statuses: `pending`, `propagating`, `completed`, `failed`, `error`, `expired`. | +| `check-connection-status` | `{ jobId }` | Read the live status of a connection job. Statuses: `pending`, `propagating`, `live`, `failed`. | | `check-order-status` | `{ orderId }` **or** `{ jobId }` | Read the live status of a domain order — by `orderId` (enterprise) or `jobId` (sharing). Provide exactly one. | | `reapply-connection` | `{ connectionId }` | Re-apply a managed connection: the control-plane recomputes its DNS from stored config and re-pushes it through the stored grant. Never supply records. Fails if the connection isn't managed or has no grant. | | `disconnect-domain` | `{ connectionId }` | Disconnect a managed connection: the control-plane reverts its DNS through the stored grant, then deletes the grant and connection. Never supply records. | diff --git a/content/reference.mdx b/content/reference.mdx index 0b90fcb..7f72081 100644 --- a/content/reference.mdx +++ b/content/reference.mdx @@ -45,7 +45,10 @@ keep both in sync when a code changes. | --- | --- | --- | | `invalid_request` | 400 | Malformed or missing input. | | `unauthorized` | 401 | Missing/invalid credential. | +| `forbidden` | 403 | Authenticated, but not permitted to perform this action. | | `not_found` | 404 | Object doesn't exist or isn't in your tenant. | +| `conflict` | 409 | The request conflicts with the resource's current state. | +| `rate_limited` | 429 | Too many requests — back off and retry. | | `quota_exceeded` | 402 | The plan's monthly quota is used up. Only `free` is hard-capped, and only where `BILLING_ENFORCE_QUOTA` is on (the hosted service currently runs meter-only, so nothing is refused today) — no paid tier is ever refused. See [Plans & quotas](/docs/billing/plans-and-quotas#overage). | | `InvalidNameservers` | 422 | The domain has no usable nameserver delegation. | | `ProviderAuthenticationError` | 422 | The end-user's DNS provider rejected the authorization/credential. |