Skip to main content

​
Troubleshooting: DOMAIN_NOT_FOUND on your branded console

A branded (white-label) console runs on your own domain — app.yourcompany.com — instead of orbit.devotel.io. Every request to it asks one unauthenticated, edge-cached lookup which organization that host belongs to, and the two public lookup endpoints ship a shared error code:
  • GET /api/v1/public/resolve-domain?host=… — host → organization and tenant. The branded console’s edge layer calls this on every request it renders.
  • GET /api/v1/public/resolve-org-domain?org_id=… — organization → its active branded domain. The primary sign-in page calls this to send signed-in subaccount users to their branded home.
Both are rate-limited (120 requests per minute per IP) and return opaque identifiers only. When the host is not a registered, active custom domain, either endpoint answers:
DOMAIN_NOT_FOUND by design means “this host is not a served branded domain,” so an active-domain 404 is a configuration gap, not a fault — but the same 404 on a domain you believe is live usually means one of the checklist steps below is out of place.

​
What a 404 means, per status

Custom-domain rows move through pending → verifying → active, with failed as the error branch. Only active rows are resolved — a half-configured domain is never served. Open Settings → Domains in the parent workspace and check the row’s status:

​
Fix steps

  1. Registered? If the row doesn’t exist in Settings → Domains, claim the domain there (an organization owner can), take the CNAME target the row shows, and point the host at it in your DNS.
  2. Verified but not active? Run the domain’s verify action. A verify that returns “We couldn’t reach your domain’s DNS in time to check the CNAME” or a SERVICE_UNAVAILABLE (503) is a transient DNS timeout — not a verdict — so the row stays in its current state and retries automatically; wait a moment and verify again. A determinate failed verdict tells you the actual reason (CNAME mismatch, NXDOMAIN) — fix DNS and re-verify.
  3. active but still 404s? Check the host string itself. The resolve lookup strips scheme, path, port, and a trailing dot before matching, so https://app.acme.com/ resolves — but a mistyped hostname, an APEX/redirect proxy host, or your own fallback rewrite can 404. Confirm the exact Host header the failing request sent.
  4. Just activated or just deleted? Success responses are edge-cached for ~60 seconds. Activate → branded pages answering DOMAIN_NOT_FOUND for up to a minute is expected and settles on its own. (The negative 404 carries no cache instruction, so a flapping DNS state shows up immediately.)
  5. The public-API wrapper — if you call resolve-domain yourself:
    • 400 VALIDATION_ERROR on a host that is shorter than 3 or longer than 253 characters — you sent it through without trimming it.
    • 429 — your poller passed 120 requests/min from one IP; back off.
    • 503 — a platform availability blip, not a code rejection; retry shortly.
  6. resolve-org-domain 404s — the organization has no active branded domain. An org whose row is pending/verifying/failed gets this until the row flips to active; the reverse lookup answers only the active domain.

​
Coverage map

Do not confuse DOMAIN_NOT_FOUND with its lookalikes:
  • Email DNS drift — an email sending domain’s SPF/DKIM/DMARC records drift and sends refuse; that page is about the email pipeline’s domain health, not the branded-console resolve lookup.
  • ACCOUNT_LOCKED at dashboard sign-in — a member-login 403 is unrelated to host resolution; check the sign-in error before assuming it is this page.
  • Tenant schema incomplete (503) — a host that resolves to an organization but hits a schema readiness 503 is a different failure class — the platform found your org; it’s still being provisioned. That page covers the recovery.

​
What to send support

If a row reads active in Settings → Domains but the branded console keeps returning DOMAIN_NOT_FOUND, open a ticket with:
  • The exact host the failing request was addressed to (copy it from the browser’s address bar — scheme and path don’t matter, only the host).
  • The time of the failure (the domain diagnostics are flapping-sensitive).
  • Your organization ID (Settings → Organization).
  • The domain row’s reported status and its last-error text.
Never paste your API key or session token — the resolve endpoints are unauthenticated and a request_id is enough for the support side.

​
See also