Why ccTLD registrations fail (and how to fix them)

ccTLD registrations fail more often than gTLD registrations because every country-code registry sets its own eligibility rules, contact requirements, and validation logic — so a single registration call has to satisfy a different rulebook for every TLD. A .com rejection usually means a duplicate name or a billing problem. A .de rejection might mean your contact address doesn’t pass the DENIC registry’s format validation, your registrant contact is missing a required field specific to German domains, or the registry itself rejected the registration without giving you a machine-readable reason. Each failure mode needs a different fix. The name.com API is built to make that diagnosis tractable: it surfaces each registry’s requirements through a single requirementsV2 schema, so you can tell which failure you’re facing — and often catch it before you ever POST.

This guide covers the three main categories of ccTLD registration failure you’ll hit through the name.com API: API-level validation errors the platform catches before the request reaches the registry, registry-level rejections that come back after submission, and eligibility blocks where the domain’s policies prevent registration entirely. By the end, you’ll know how to diagnose which category you’re in, how to read the requirementsV2 schema before you POST, and how to separate data errors from eligibility blocks that no field correction will resolve.

Why ccTLDs fail more often

Every ccTLD operates under rules set by its own registry — and those rules don’t map cleanly onto the shared fields the name.com API exposes, which is why ccTLD registrations fail at a higher rate than gTLD registrations.

DENIC runs .de. Nominet runs .uk. AFNIC runs .fr. Each registry defines its own contact field requirements, eligibility criteria, and validation logic independently of ICANN policy. When you register a .com, the name.com API sends your contact data to a single shared registry (Verisign) that accepts a standard set of fields. When you register .ca, the same API call has to satisfy both the name.com API’s own validation layer and the CIRA registry’s separate requirements. The requirementsV2 response for .ca requires two TLD-specific fields, namely lang_pref (EN or FR) and legal_type (a CIRA-defined enum covering Canadian Corporation, Canadian Citizen, Permanent Resident, and others) in addition to standard contact fields. It also enforces a conditional: if legal_type is an organization of some kind, companyName becomes required in the registrant contact. Miss any of these and the registration fails.

The name.com API surfaces requirements like these through the requirementsV2 endpoint and enumerates all required fields, constraints, and conditional logic that varies by registrant type within the same TLD. Pull that data before you build your registration flow for any ccTLD.

Why ccTLD registrations fail differently than gTLD registrations

ccTLD registration failures split into two classes: malformed or missing tldRequirements fields (fixable by correcting your payload) and eligibility blocks (where the registrant doesn’t meet the registry’s nexus or residency requirement regardless of data quality). Both can produce a 400 Bad Request with similar error text, but only one is solvable by editing fields.

The name.com API acts as a consistent interface across all TLDs, but behind that interface, each ccTLD registry enforces its own eligibility rules independently. DENIC governs .de. The EURid registry governs .eu. GoDaddy Registry governs .us. None of them coordinate on error format, eligibility logic, or how they surface rejections through intermediary registrars. The diagnostic fork later in this guide shows how to separate the two failure classes — but the prerequisite is reading the requirementsV2 schema before you POST.

Category 1: API validation errors

API validation errors are failures the name.com platform catches before your request reaches the registry. They’re also the easiest to fix because the API tells you exactly what went wrong.

These errors come back before your request reaches the registry. The name.com API validates your payload and returns an error if something is missing or malformed.

Missing required TLD-specific fields

Some ccTLDs require fields that gTLD registrations do not. .ca, for example, requires lang_pref and legal_type in the tldRequirements object. These are fields that don't exist in a standard gTLD registration payload. Other ccTLDs have their own equivalents. If you omit a required tldRequirements field, the API returns a 400 identifying what’s missing. The fix is to call requirementsV2 for your target TLD and map those fields into your registration payload before you POST.

Phone number format validation

The name.com API requires phone numbers in E.164 format: a + followed by the country code and subscriber number, no spaces or punctuation. +14155552671 is valid. (415) 555-2671 is not.

This trips up forms that collect phone numbers in a local format and pass them through without normalization. Add a normalization step before submission that strips formatting and prepends the correct country code.

Address field length violations

Some registries cap field lengths below what you’d consider reasonable. If your registrant’s address line exceeds the registry’s character limit, the API validation layer will reject it before submission. Truncating address fields is a bad idea — it can cause downstream issues with registry validation. The better fix is to surface a character limit in your UI at the point of collection.

Category 2: registry rejections

Registry rejections pass the name.com API’ validation layer, reach the registry, and are refused there, which makes them harder to diagnose because the error quality depends entirely on how well the registry communicates rejection reasons.

Your payload passes the name.com API’s own validation, the request goes to the registry, and the registry rejects it. The error you get back depends on how well the registry communicates rejection reasons, which varies a lot by ccTLD.

Structured registry error codes

Some registries return structured error codes you can map to specific problems. DENIC, for example, returns EPP result codes that indicate whether the failure was a data validation issue, a policy violation, or a system error. If you’re seeing registry rejections for .de, log the full error response body, not just the HTTP status code.

Opaque rejections

Some registries return generic rejection messages that don’t identify which field failed. When you hit one of these, work through a checklist: confirm every field matches the format the registry expects, verify the registrant contact data matches the registrant’s actual identity, and check whether the domain itself is reserved or restricted at the registry level.

Phone number and address format

Even when your payload passes name.com’s own validation, some registries run additional format checks on contact fields. Log the full error response body when debugging registry rejections, since the details field may identify the specific field the registry rejected.

Category 3: eligibility blocks

Eligibility blocks are policy enforcement, not technical errors — the registrant simply doesn’t qualify to register the domain under the registry’s rules, and no data correction will change that outcome.

Residency and nexus requirements

Many ccTLDs restrict registration to entities with a presence in the relevant country or region. .ca requires Canadian citizenship, permanent residency, or a qualifying Canadian legal presence. .eu requires residency or incorporation in an EU member state. If your platform serves users who might not meet these requirements, your registration flow needs to check eligibility before attempting registration. The tldRequirements response documents the eligibility criteria for TLDs that enforce them at the API level, and you can use those to build a pre-registration eligibility check that surfaces a clear explanation to the user rather than a confusing API error.

Trademark and reserved name blocks

Some ccTLD registries maintain lists of reserved or restricted names. Certain strings are reserved for government use, blocked due to trademark claims, or restricted to specific registrant categories. These blocks come back as registry rejections with no path to resolution for ineligible registrants.

Query the name.com API’s availability check endpoint before presenting a domain as available in your UI. A domain that returns available at the availability check stage can still fail at registration if the registry’s reserved list check runs only at registration time, but availability checking eliminates the obvious cases.

Trustee and local presence services

Some registrants want a ccTLD domain but don’t meet the local presence requirement. Several registries allow a trustee or local presence service to satisfy this requirement on the registrant’s behalf. This is registry-specific, and not all ccTLDs permit it. If you’re building a registration flow that handles ccTLDs at scale, check whether the registries you support allow trustee arrangements and factor that into your eligibility logic.

Reading the requirementsV2 response before you POST

Always call GET /core/v1/domaininfo/requirementsV2/{tld} before POST /core/v1/domains — the response is a JSON Schema Draft-07 document that encodes every required field, value pattern, and conditional branch for that TLD, and it’s the only reliable source of truth for registry requirements that change over time.

This endpoint returns a JSON Schema Draft-07 document. It has three top-level objects worth understanding:

• tldInfo — read-only TLD metadata: grace periods, auto-renew periods, whether WHOIS privacy is supported. Use this to configure renewal and lifecycle logic, not registration validation.
• contacts — JSON Schema definitions for each contact role (registrant, adminContact, techContact). Required fields, type constraints, format patterns. This is where contact-role requirements for specific TLDs live.
• tldRequirements — TLD-specific fields beyond the standard contact schema. This is where registry-specific requirements live, and where the if/then/else conditionals appear.

The tldRequirements object is where most ccTLD-specific logic lives, but the conditional logic itself appears at the top level of the schema in an allOf block. The .ca requirements response shows how this works in practice:

// GET /core/v1/domaininfo/requirementsV2/ca
// Truncated for clarity
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "tldRequirements": {
    "type": "object",
    "properties": {
      "lang_pref": {
        "title": "Language Preference",
        "oneOf": [
          { "const": "EN", "title": "English" },
          { "const": "FR", "title": "French" }
        ]
      },
      "legal_type": {
        "title": "Legal Type",
        "oneOf": [
          { "const": "CCO", "title": "Canadian Corporation" },
          { "const": "CCT", "title": "Canadian Citizen" },
          { "const": "RES", "title": "Permanent Resident" }
          // ... additional legal types
        ]
      }
    },
    "required": ["lang_pref", "legal_type"]
  },
  "allOf": [
    {
      "if": {
        "properties": {
          "tldRequirements": {
            "properties": {
              "legal_type": {
                "enum": ["ASS", "CCO", "EDU", "GOV", "HOP", "INB", "LAM", "MAJ", "OMK", "PLT", "PRT", "TDM", "TRD", "TRS"]
              }
            }
          }
        }
      },
      "then": {
        "properties": {
          "contacts": {
            "properties": {
              "registrant": {
                "required": ["companyName"]
              }
            }
          }
        }
      }
    }
  ]
}

That if/then block is the conditional you’d most likely miss if you were working from just the documentation. If legal_type is set to an organization type (e.g Canadian Corporation, Government, Educational Institution) then companyName becomes required in the registrant contact. Register as an individual (CCT or RES) and the condition doesn’t fire. Submit an organization legal_type without companyName and you’ll get a 400, even if the rest of your contact data is perfectly valid.

Because the response is JSON Schema Draft-07 compliant, you can drop it directly into ajv and run local pre-validation before calling POST /core/v1/domains. That eliminates a round-trip to the registry for every field-level mistake you catch early, and the schema’s conditionals surface as validation errors locally rather than as opaque registry rejections after the fact.

What malformed and missing tldRequirements fields produce

When a POST /core/v1/domains call fails due to malformed or missing fields, the name.com API returns a 400 Bad Request where the message field contains all field-level errors as a semicolon-separated string, with each entry a dot-notation path identifying exactly which field failed and why.

A .ca registration submitted without tldRequirements fields or required registrant contact fields produces the following:

// HTTP 400 Bad Request
// POST /core/v1/domains — .ca registration with missing tldRequirements and contact fields
{
  "message": "tldRequirements error: tldRequirements.lang_pref: This field is required and cannot be empty; tldRequirements.legal_type: This field is required and cannot be empty; domain.contacts.registrant.phone: This field is required and cannot be empty"
}

Each dot-notation path in message maps directly back to the schema: tldRequirements.lang_pref and tldRequirements.legal_type are the required fields from the .ca tldRequirements object; domain.contacts.registrant.* entries correspond to the required fields in the contacts.registrant schema. The requirementsV2 response told you what was required; the error tells you what you missed.

The same pattern applies to any ccTLD with tldRequirements. For .us, the two required fields are nexus_category (C11–C32, identifying the registrant’s qualifying nexus) and app_purpose (P1–P5, the intended use of the domain). Submit without either and the 400 message will reference them by their dot-notation paths.

One common trigger worth calling out: submitting a tldRequirements object with wrong field names. The keys in tldRequirements are defined by each registry’s own convention and aren’t standardized across TLDs. .ca uses lang_pref and legal_type; .us uses nexus_category and app_purpose. Verify the exact key names from the requirementsV2 response for each TLD you’re integrating. Don’t assume they’re portable from one ccTLD to another.

Eligibility failures vs. data errors: the diagnostic fork

The key distinction between data errors and eligibility failures is where in the request lifecycle the failure occurs: data errors are caught during field validation before the registry is reached, while eligibility failures come back from the registry itself after your payload passes every schema constraint.

Data errors fail during field validation. The API (or the ajv validator running locally against the requirementsV2 schema) catches a missing required field, a value that doesn’t match a pattern constraint, or a contact role mismatch. These failures happen before the request reaches the registry. Fix the data, resubmit, done.

Eligibility failures work differently. The field validation passes. Your payload satisfies every JSON Schema constraint in the requirementsV2 response. The POST /core/v1/domains call still returns a rejection because that rejection comes from the registry itself, not from API-level validation. The registrant’s actual situation — citizenship, residency, business incorporation jurisdiction — doesn’t meet the registry’s underlying requirement, regardless of what values were submitted in the fields.

If your payload validates cleanly against the requirementsV2 schema in ajv but the POST still fails, you’re in eligibility territory. That’s a structural problem, and no field correction resolves it.

ccTLD error breakdown by category

.us deserves extra attention because the nexus requirement is frequently underestimated. A foreign organization can qualify under C31 or C32 by demonstrating regular US business activity or maintaining a US office, but this is a genuine eligibility question, not a field formatting issue. Submitting nexus_category: C31 without a real US operational presence doesn’t make the registration valid. It does however make the registration vulnerable to later revocation when the registry conducts compliance verification.

.de appears in two categories deliberately. The authorized admin contact requirement is technically a workaround that keeps the domain accessible to non-German registrants, but it’s also a specific contact-role constraint. Which framing applies depends on which direction you’re debugging from.

Building a reliable ccTLD registration flow

A reliable ccTLD registration flow follows one consistent pattern: check requirements before submission, validate locally before calling the API, and handle errors at the right layer — catching data errors in ajv before you POST and recognizing eligibility blocks as structural problems that field corrections cannot resolve.

Pull tldRequirements for each ccTLD you support and build that data into your form validation. Check eligibility before the user reaches the payment step. Normalise contact fields (phone numbers, address formats, character limits) before constructing the API payload. Log full error response bodies on registry rejections, because the detail you need is often in the error body rather than the HTTP status code.

The name.com API documentation at docs.name.com covers the requirementsV2 endpoint and the supported ccTLD schemas. Start there when you’re adding support for a new ccTLD, and test with the sandbox environment before pushing to production.

The resolution workflow: from error to fix

Run this sequence for every ccTLD you’re integrating, before any production traffic hits the endpoint.

Step 1: Fetch the schema. Call GET /core/v1/domaininfo/requirementsV2/{tld} against https://api.dev.name.com for the target TLD. Pull the live schema rather than working from documentation assumptions, because registry requirements change and the schema reflects current rules.

Step 2: Run local validation. Load the schema into ajv (configured for Draft-07) and validate your registrant payload against it. Pay particular attention to the if/then/else conditionals in the top-level allOf block. These branch on registrant type or contact-role conditions that are easy to overlook in a surface read of the schema.

Step 3: POST to the sandbox. Authenticate with your -test username (e.g., reseller123-test) and your sandbox API token. Sandbox credentials can take up to 15 minutes to activate after creation, so account for that in your testing setup. A 400 in the sandbox carries the same diagnostic value as a 400 in production, without the cost or the registry record.

Step 4: Parse the error. A 400 where the message string references a specific tldRequirements key is a data error. Cross-reference it with the requirementsV2 schema and correct the field. If your payload passes ajv validation but the sandbox POST still fails with a message that doesn’t reference a specific field, you might be looking at a registry-level eligibility rejection.

Step 5: Resolve by error class. Data errors: fix the field and re-validate through ajv before resubmitting. Eligibility blocks: evaluate the structural options for that specific TLD.

• .de: A Germany-based authorized admin contact satisfies DENIC’s requirement for non-German registrants. This is a supported, well-documented workaround.
• .eu and .us: No trustee equivalent exists. For .eu, the registrant country must be one of the EU/EEA member states accepted by EURid. Verify the current list against the requirementsV2/eu response, which currently covers EU member states plus Iceland, Liechtenstein, and Norway. For .us, the registrant must satisfy one of the five C1x/C2x/C3x nexus categories. Contact substitution doesn’t route around either of these.

Step 6: Promote to production only after sandbox success. Production base URL is https://api.name.com. The same HTTP Basic Auth credentials apply to both environments (production token for production, sandbox token for api.dev.name.com).

One operational note: keep automated validation loops under 20 requests/second or 3,000/hour to avoid HTTP 429 errors. Build exponential backoff into retry logic.

Pre-validate before you register

Start with the next ccTLD in your integration queue. Call GET /core/v1/domaininfo/requirementsV2/{tld} against https://api.dev.name.com and pipe the response into ajv against your standard registrant payload. Pay particular attention to the if/then/else conditionals in the top-level allOf block. These will surface conditional requirements that are easy to miss in a flat read, such as .ca's companyName requirement that only activates for organization legal_type values.

Do this before a single production registration attempt. The upfront cost is one GET call and a few minutes with a validator. Skip it and you risk a failed POST, a debugging loop, and eventually discovering the problem was structurally unsolvable by data correction alone.

Start integrating ccTLD registration with a free name.com API account — the requirementsV2 endpoint is available immediately.