Authentication and Errors

This API section covers calls made to Custom Domain Kit, not the setup-session endpoint that your SaaS app implements.

Authentication

Dashboard and control-plane API routes require an authenticated Custom Domain Kit dashboard session. Server-side integrations that operate on behalf of the account owner must use the same authenticated context available to the product.

Browser setup flows should use the embedded setup UI and short-lived setup tokens instead of calling control-plane APIs directly.

Error Shape

Errors use this JSON shape:

{
  "error": {
    "code": "bad_request",
    "message": "Hostname is required.",
    "details": {}
  }
}

Common Codes

Code	HTTP	Meaning
`bad_request`	400	Invalid JSON or invalid input.
`unauthorized`	401	Authentication is missing or invalid.
`not_found`	404	Resource does not exist or does not belong to the caller.
`replacement_required`	409	Hostname already exists and needs replacement confirmation.
`payment_required`	402	Plan or entitlement does not allow this action.
`bad_gateway`	502	Upstream provider or DNS service could not be reached.

Handling Errors

Show bad_request messages near the form field that caused them.
Send account owners to billing when you receive payment_required.
Treat replacement_required as a user-confirmed ownership flow.
Retry bad_gateway only after confirming DNS or provider availability.