Skip to content

API-09 / API-11: correct the connection-status enum and complete the error-code table #8

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
ever-just wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

API-09 / API-11: correct the connection-status enum and complete the error-code table #8

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 7 additions & 3 deletions content/api-reference/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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. |
Expand Down
2 changes: 1 addition & 1 deletion content/mcp/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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. |
Expand Down
3 changes: 3 additions & 0 deletions content/reference.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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. |
Expand Down