Summary

Every domain name reseller eventually hits a failed ccTLD registration. Learn to tell validation errors, registry rejections, and eligibility issues apart, then fix them or escalate with a support request that gets resolved the first time.

A failed country-code top-level domain (ccTLD) registration through the name.com Core API can have several causes. The request may contain missing or invalid fields, a registry may reject the registration after processing it, or the registration may involve eligibility or compliance requirements that need further investigation. These situations call for different responses, so diagnosing the failure before retrying is important.

This guide provides a practical framework for distinguishing between these scenarios, using the API's validation responses and registry notifications to investigate what happened, and deciding when to contact our reseller support.

You'll learn how to use the TLD requirements schema to identify correctable request errors, investigate registry rejections, recognise when contact verification or eligibility requirements may be relevant, and prepare a useful support request to send to reseller@name.com. The three categories used throughout this guide are a useful troubleshooting framework.

How to diagnose ccTLD registration failures

A useful first step is to identify what kind of failure you're dealing with. The following three scenarios provide a practical troubleshooting framework:

Request validation failures occur when the API identifies missing or invalid fields in a registration request. For example, a .ca registration missing tldRequirements.lang_pref can return a field-level validation error. Check the response body, make a GET request to /core/v1/domaininfo/requirementsV2/{tld}, correct the payload, and resubmit. Passing validation does not guarantee that the registry will accept the registration.

Registry rejections can occur after a registration request has been accepted by the API. When our system sends a domain.registry.rejection webhook, inspect its reason and available registration identifiers, including orderId and orderItemId, to investigate the failure. Determine whether the cause can be corrected or whether you need further assistance before continuing downstream provisioning. Some .uk registrations, such as certain ltd.uk, plc.uk, and net.uk applications require manual referral under Nominet's rules; this is a registry-specific example, not a universal ccTLD workflow.

Eligibility and compliance issues involve requirements beyond basic payload validation. These may require additional registrant information, contact verification, or action in response to a registry compliance notice. Check the relevant TLD requirements and any domain.registry.compliance_notice notification. Don't assume that every compliance issue is permanent or that resubmitting the same request will resolve it.

Use the table below to choose an appropriate next step.

Situation

Diagnostic signal

Recommended next step

Request validation failure

Response identifies missing or invalid fields

Correct the payload using the TLD requirements schema before resubmitting.

Registry rejection

domain.registry.rejection webhook with a rejection reason and registration identifiers

Investigate the reason and determine whether correction or support is needed.

Eligibility or compliance issue

Relevant TLD requirements, compliance notice, or contact-verification issue

Identify the specific requirement and follow its documented remediation steps.

Unclear or widespread failure

No clear cause, or multiple registrations fail unexpectedly

Review available diagnostics and check status.name.com for relevant service incidents before drawing conclusions.

How to fix request validation errors

The /core/v1/domaininfo/requirementsV2/{tld} endpoint returns a JSON Schema describing registration requirements for a given TLD. You can use this schema to validate registration payloads locally before submitting them with a POST call to /core/v1/domains. A JSON Schema validator such as Ajv can catch missing fields and invalid values before the request reaches the API.

The .ca TLD provides a useful example. Its schema defines required registrant contact fields and TLD-specific fields, including tldRequirements.lang_pref and tldRequirements.legal_type. The permitted language values are EN and FR; legal_type must match one of the values defined in the returned schema. For example, CCO represents a Canadian corporation, while RES represents a Canadian citizen resident.

When required fields are missing, the API can return a validation message identifying the fields that need attention. In a captured sandbox response, the message identified missing tldRequirements.lang_pref, tldRequirements.legal_type, and several required registrant contact fields. Use the actual response body to identify the specific fields to correct rather than assuming every validation error has the same format.

The relevant fields in a registration payload are illustrated below. This is a partial example, not a complete registration request; the required registrant contact fields and any other applicable properties must also be supplied.

JSON
{
  …
  "domain": {
    "domainName": "example.ca"
  },
  "tldRequirements": {
    "lang_pref": "EN",
    "legal_type": "CCO"
  }
  …
}

The correction workflow is straightforward: inspect the error response, identify the affected fields, consult the schema for valid values, correct the payload, and resubmit.

Requirements vary by TLD. For example, .us registrations use fields such as nexus_category and app_purpose, so always retrieve the schema for the TLD you're registering. Passing local schema validation does not guarantee registry acceptance; registries may apply additional eligibility or policy checks beyond the schema.

When to investigate further and when to escalate

Correct and retry when the API response identifies specific missing or invalid request fields. Consult the requirementsV2 schema, correct the payload, and resubmit. We recommend including an X-Idempotency-Key header on domain registration requests. This helps prevent duplicate purchases when retrying a timed-out request. The idempotency cache is valid for one hour, so don't assume the same key will protect against duplicate purchases beyond that window.

Interpret HTTP errors carefully. A 502 Bad Gateway generally indicates a gateway or upstream communication problem, but it doesn't establish whether a registration succeeded or failed. Investigate the outcome before submitting another registration request. A 429 Too Many Requests indicates rate limiting; follow the Retry-After header if the response includes one. Neither status code automatically means that you need to escalate, and neither alone establishes what happened at the registry.

Investigate registry rejections when a domain.registry.rejection webhook arrives. Read the reason field. Some rejections reflect correctable issues (invalid contact format, missing nexus field) that you can address and resubmit. Others reflect registry policy that requires registrant action or escalation. The rejection payload's orderId lets you correlate the event against your internal order records.

Check for wider service issues before attributing a cluster of failures to individual registry problems. If you're seeing multiple unexpected failures across different domains or TLDs, status.name.com should be your first stop. A platform-level incident explains patterns that would otherwise look like separate registry rejections.

Contact reseller support at reseller@name.com when the rejection reason is unclear, the documented remediation steps don't resolve the issue, or you need help interpreting what the registry returned. Include the request details and troubleshooting you've already performed (see the checklist below) so support can investigate without requesting basic diagnostics a second time.

Registry restrictions, contact verification, and eligibility issues

Domain restrictions, contact verification failures, and TLD eligibility requirements are distinct from request validation errors and registry rejections. Identifying which applies helps you choose the appropriate next step.

Distinguish domain locks by their effect. ICANN requires registrants to verify their email address within 15 days of registration or a change to contact information (see our Domain Locks guide). For high-volume reseller accounts, VerificationClientHold may be applied when contacts remain unverified after this period. This status places a hold at the registry level, removing the domain from DNS. VerificationHold, used for retail customers and medium-to-low-volume reseller accounts, redirects the domain to a name.com landing page instead. Other locks have different effects: for example, RegistrarLock restricts transfers, while ClientHold may be applied for compliance or abuse reasons. Don’t assume that any of these states caused a new registration to fail.

To inspect a domain’s current lock information, use a GET call to /core/v1/domains/{domainName} and examine the locks array. The top-level locked boolean alone doesn’t identify the restriction or explain its effects. Consult the Domain Locks documentation to interpret the specific lock.

Check contact verification when relevant. Our API provides endpoints to list unverified contacts and resend verification emails. Programmatic verification is also available to approved reseller accounts; if you need access, contact our support team. See the contact verification API reference for the workflow and current endpoint details. Resolving an unverified contact does not necessarily clear a separate domain hold or satisfy a TLD’s eligibility requirements.

For TLD-specific eligibility fields, perform a GET call /core/v1/domaininfo/requirementsV2/{tld}. If the registry raises a compliance issue, inspect the domain.registry.compliance_notice webhook for the reported issue and any requested remediation. If the requirements or notification don’t make the next step clear, contact reseller support at reseller@name.com.

How to prepare a useful reseller support request

A well-prepared support request gives our reseller support team (reseller@name.com) the context they need to investigate without first asking for basic details. Include the information relevant to your case, rather than sending only a domain name and a brief description of the failure.

Include the following:

Domain details

  • Domain name and TLD: The full domain name you attempted to register.
    Request details
  • API endpoint: For example, a POST to /core/v1/domains.
  • Approximate UTC timestamp: When you made the request.
  • Relevant request payload: Include the domain object and tldRequirements where applicable. Redact credentials, authorization headers, and other secrets.
  • X-Idempotency-Key: Include the value if you used one.
    API response
  • HTTP status code: The exact status returned.
  • Response body: The complete JSON or text response.
  • Relevant response headers: Include headers that may help explain the failure, such as Retry-After for rate limiting.
    Registration identifiers and notifications
  • orderId and orderItemId: Include these if available in the API response, webhook, or relevant transaction records.
  • Webhook payloads: Include the full domain.registry.rejection or domain.registry.compliance_notice payload if you received one.
    Troubleshooting already performed
  • Schema validation: Whether you checked the payload against the output of GET /core/v1/domaininfo/requirementsV2/{tld}.
  • Payload corrections: What you changed and what happened after each attempt.
  • Contact verification: Relevant verification status checks, if contact verification may be involved.
  • Status page: Whether you checked the name.com status page for relevant service incidents.

Eligibility or compliance information

If the failure involves a TLD-specific eligibility or compliance requirement, include the relevant details or evidence, for example, Canadian eligibility information for .ca or nexus information for .us.

If contact verification appears relevant but your reseller account lacks access to the programmatic verification endpoint, mention this in the request and ask about access.

You don't need every item for every case. Include what's relevant to the failure, and ensure the request and response details are sufficient to reproduce or investigate the issue. Never send passwords, API credentials, or authorization headers.

Frequently asked questions

What does serverHold mean for a ccTLD domain?

serverHold is a registry-level EPP status that prevents a domain from being published in DNS. The appropriate next step depends on the registry and the reason for the hold. Check the domain’s current status and any relevant notifications, then contact reseller@name.com if the cause or available remediation options aren’t clear.

Why is my ccTLD domain stuck in pendingCreate after the API returned success?

An accepted API request does not necessarily mean the registration is complete. Check the current domain status using GET /core/v1/domains/{domainName}, review the relevant order details, and look for domain.registry.rejection or domain.registry.compliance_notice notifications. Don’t assume that pendingCreate is always a normal intermediate state for every ccTLD. If the status persists and the next step is unclear, contact reseller@name.com with the domain name, available order identifiers, the original request’s UTC timestamp, and the current status.

What’s the difference between clientHold and serverHold?

clientHold is applied at the registrar’s request, while serverHold is applied by the registry operator. Both can prevent a domain from resolving through DNS, but their causes and remediation paths differ. Check the full locks array returned by GET /core/v1/domains/{domainName} and consult the name.com Domain Locks documentation to interpret the specific status. Don’t assume that every hold can be cleared through the same API operation.

When is it safe to retry a failed ccTLD registration?

If the API identifies specific missing or invalid fields, correct them using the relevant requirementsV2 schema before resubmitting. For domain creation requests, name.com recommends using an X-Idempotency-Key to help prevent duplicate purchases when retrying a timed-out request. The idempotency cache is valid for one hour, so don’t rely on the same key to protect against duplicate purchases beyond that period. If you receive a 502 Bad Gateway, first investigate whether the registration succeeded; if you receive a domain.registry.rejection webhook, inspect the rejection reason before deciding whether to retry.

Wrapping up

Diagnose before you act. Use the requirementsV2 schema to correct request validation errors, inspect domain.registry.rejection notifications to investigate registry rejections, and review TLD requirements, domain locks, and contact verification when eligibility or compliance issues may be involved.
A structured troubleshooting process helps you avoid blind retries and prepare useful support requests. When the documented workflow doesn't clarify the next step, contact reseller@name.com with the relevant request payload, API response, webhook notifications, and troubleshooting already performed.
For API documentation and integration guidance, visit docs.name.com. If you're building a domain registration integration, contact our reseller team to discuss your requirements and pricing.