Custom domain errors

What each custom domain problem code means and how to fix it, from a missing TXT record to a blocked certificate.

When a custom domain is not working, the console shows a message on the domain and the API returns a problem code in error.code. Find the code in the following sections, fix the cause, then click Check again or call POST /applications/{applicationId}/domains/{domainId}/refresh.

Only problems you control count toward the 7-day limit after which a waiting domain fails: the ownership record, the DNS record, and CAA records. platform_capacity, cdn_error, dns_lookup_failed, and tls_probe_failed are on the Gigadrive Network side. The check keeps repeating while they last, and they never fail a domain.

Ownership

Code	Meaning	Fix
`ownership_record_missing`	No `_gigadrive-challenge` `TXT` record was found.	Publish the `TXT` record the console lists.
`ownership_record_mismatch`	A `TXT` record exists, but its value is a different token.	Replace the value with the token listed for this domain.
`dns_propagating`	Some public resolvers see the record and others do not yet.	Wait. The check repeats automatically.
`ownership_timeout`	Ownership was not verified within 7 days.	Publish the record, then click Check again.

Every public resolver Gigadrive Network uses must see the token before the domain counts as verified.

DNS

Code	Meaning	Fix
`dns_record_missing`	The hostname has no record pointing anywhere.	Publish the `CNAME` record, or the `ALIAS` record for an apex domain.
`dns_record_mismatch`	The hostname points somewhere other than Gigadrive Network.	Change the record value to `cname.gigadrive-dns.net`.
`dns_conflicting_records`	Some addresses point at Gigadrive Network and others elsewhere.	Remove the old `A` and `AAAA` records for the hostname.
`dns_proxied_by_cloudflare`	The record is proxied by Cloudflare.	Set the record's proxy status to DNS only.
`dnssec_failure`	Resolvers reject the domain's records because DNSSEC is broken.	Fix or turn off DNSSEC at your DNS provider and registrar. The `DS` record must match the zone's keys.
`dns_lookup_failed`	The lookup failed on the resolver side, or the edge address list was temporarily unavailable.	Wait. The check repeats automatically.
`dns_timeout`	The record was not found within 7 days.	Publish the record, then click Check again.

Certificates

Code	Meaning	Fix
`cert_blocked_caa`	The domain's `CAA` records do not allow Let's Encrypt.	Fix the `CAA` records as described after this table, then click Check again.
`cert_issuance_failed`	The certificate authority could not validate the hostname yet.	Check that the DNS record is correct. The request repeats automatically.
`cert_rate_limited`	Certificate requests for the hostname are paused.	Wait. Requests resume automatically within 24 hours.
`cert_timeout`	No certificate could be issued within 7 days.	Fix the DNS record, then click Check again.
`cert_expiring`	The certificate expires within 14 days and was not renewed yet.	Check that the DNS record still points at Gigadrive Network.
`tls_probe_failed`	The hostname does not serve a valid certificate right now. This can appear while the certificate is being issued.	Check that the DNS record still points at Gigadrive Network.

To fix cert_blocked_caa, make sure one CAA record allows Let's Encrypt, for example 0 issue "letsencrypt.org". If that record sets validationmethods, include http-01 in the list. Remove any accounturi parameter from it, and remove any record that has the critical flag, 128, with a tag the certificate authority does not recognize. CAA records on a custom domain has the full rules.

Code	Meaning	Fix
`hostname_in_use_elsewhere`	The hostname is registered with another CDN account.	Remove it from the other service, then click Check again.
`wildcard_not_allowed`	The domain is a wildcard, such as `*.example.com`. Wildcard domains are not supported.	Remove this domain and add each hostname separately.
`platform_capacity`	Gigadrive Network is adding capacity for custom domains.	Nothing. The domain is set up automatically once capacity is available.
`cdn_error`	A call to the CDN failed. The message can end with `The CDN reported:` and the CDN's own explanation.	Nothing. The step repeats automatically.

Suspended domains

A domain in the suspended state does not serve traffic. The console shows why on the domain, and the API returns the reason in suspendedReason:

Reason	Meaning	Fix
`plan_limit`	Your organization stayed over its custom domain limits for the 14-day grace period after the warning email.	Upgrade the plan or remove other domains. The domain resumes automatically once the organization is within its limits.
`claimed`	Another organization verified the domain and claimed the hostname.	If you control the domain, move it back by claiming it for your application.
`admin`	Gigadrive staff suspended the domain.	Contact support.

Error pages on the domain

When a visitor opens the domain and it cannot serve your application, the edge answers with a branded page that shows an error code:

Code	Status	Meaning	Fix
`EDGE_DOMAIN_NOT_CONFIGURED`	`404`	The hostname points at Gigadrive Network, but no custom domain in the Active or Needs attention state uses it.	Add the hostname to an application. If you already did, fix the problem shown on the domain until it is Active.
`EDGE_DOMAIN_NO_DEPLOYMENT`	`404`	The domain is connected, but the application has no deployment for it yet.	Deploy the application, or the branch the domain serves.
`EDGE_DOMAIN_LOOKUP_FAILED`	`503`	Gigadrive Network could not look up the domain's configuration.	Retry shortly. The error is temporary.

Neither the CDN nor browsers cache these pages. After a domain becomes active, the edge can take up to a minute to start serving it.

Errors from the domain API

The API rejects some requests outright, for example adding a hostname, claiming one, or removing a verified domain. The error body carries a message in error, a stable code, and sometimes a reason:

{
  "error": "shop.example.com is attached to another organization. Verify the domain, then claim it.",
  "code": "domain_in_use",
  "reason": "other_organization"
}

Find the code in the following table:

Code	Status	Fix
`invalid_domain`	`400`	Enter a hostname only, such as `shop.example.com`, without a scheme, path, or port. `reason` names the problem, for example `not_a_hostname`, `ip_address`, `single_label`, `public_suffix`, `label_too_long`, `invalid_characters`, or `mixed_script`. With `reason` set to `wildcard_not_allowed`, the hostname is a wildcard such as `*.example.com`, which cannot be added or claimed; add each hostname separately.
`blocked_domain`	`400`	Use a domain you own. `gigadrive.app` and other platform domains cannot be attached. `reason` is `blocked`.
`invalid_target`	`400`	Check the branch or redirect target. `reason` tells you which part is wrong: `branch_not_found`, `branch_required`, `redirect_target_invalid`, `redirect_loop`, `redirect_status_invalid`, `redirects_not_available`, `redirect_cannot_be_primary`, or `wildcards_not_available`. With `reason` set to `redirect_cannot_be_primary`, make a domain that serves your application primary instead of a redirect domain.
`unauthenticated`	`401`	The access token is expired, unrecognized, or revoked. Request a new token and retry once.
`insufficient_scope`	`403`	The token lacks the scope the endpoint needs: `network:domains:read`, `network:domains:write`, or `network:domains:delete`. Use an API key that carries it, as described in Scopes.
`forbidden`	`403`	Your credentials cannot reach this application or organization, or cannot make this change. Deployment and Function tokens cannot add, update, check, claim, or remove custom domains. Only a signed-in user or an organization API key can claim a hostname, or add, verify, or remove an organization's verified domain. A claim made with an application API key carries `reason` set to `actor_not_allowed`.
`feature_disabled`	`403`	Custom domains are turned off.
`not_found`	`404`	The application, custom domain, or verified domain does not exist, belongs to another application, or your credentials cannot see it. Check the IDs in the path. A domain that is being removed also returns `404`.
`domain_in_use`	`409`	The hostname is already attached. With `reason` set to `same_organization`, an application of your organization holds it; remove it there first. With `reason` set to `other_organization`, move the domain.
`conflict`	`409`	The domain's current state prevents the change. With `reason` set to `state_changed`, the domain changed while your request ran and nothing was saved; read the domain again and retry. With `primary_taken`, another domain of the application became primary at the same time; read the domains again and retry. With `admin_suspended`, Gigadrive staff suspended the domain, so it cannot be removed; contact support.
`claim_refused`	`409`	The claim was refused. With `reason` set to `not_attached_elsewhere`, no other organization holds the hostname, so add it instead. With `ownership_not_verified`, your organization has not verified the domain. With `ownership_not_live`, the `TXT` record was missing when you claimed. Verify the domain, keep the `TXT` record published, and claim again.
`ownership_exists`	`409`	Your organization already added this domain for verification. Verify the existing entry instead of adding it again.
`ownership_in_use`	`409`	Custom domains still rely on this domain: domains attached through the verified domain, or, while it awaits verification, domains waiting for its `TXT` record. Remove those custom domains first, then remove the domain.
`quota_exceeded`	`429`	Your plan's limit is reached. Remove a domain or upgrade the plan. With `reason` set to `daily_add_limit`, wait until the 24-hour add limit frees up. Claims count toward both limits, like adding a domain. The response has no `Retry-After` header.
`rate_limited`	`429`	You checked, verified, or claimed too soon after the previous attempt. Wait the number of seconds in the `Retry-After` header, also returned as `retryAfterSeconds` in the body, then try again.
`internal_error`	`500`	The request failed on the Gigadrive Network side. Retry with backoff.

A malformed ID in the path, a body that does not match the endpoint's schema, or a PATCH body without target or primary returns 422 before any of these checks. That response uses the validation error shape and has no code.