Troubleshoot your first API call

Overview

This page covers errors you're likely to encounter during your first API calls. If you're getting started, go to the quickstart for the happy path first.

curl: (6) Could not resolve host

Symptom: curl reports it can't resolve api.godaddy.com.

Cause: DNS can't resolve the API hostname. Typically a network or proxy issue.

Resolution:

• Verify internet connectivity (curl https://google.com).
• If behind a corporate proxy, configure curl to use it with the --proxy flag or HTTPS_PROXY environment variable.
• If on a VPN, try disconnecting temporarily to rule out DNS filtering.

401 Unauthorized on first call

Symptom: Your first API call returns 401.

Cause: The Authorization header is missing or the token value is wrong.

Resolution:

• Confirm the environment variable is set: echo $GODADDY_PAT should print the token value.
• Verify the header format is Bearer <token> — no extra quotes, no "Bearer " with a trailing space.
• Make sure you exported the variable in the same shell session where you're running curl.
• Go to Troubleshoot authentication for deeper auth issues.

403 Forbidden on availability check

Symptom: GET /v3/domains/check-availability returns 403.

Cause: The token doesn't have the domains.domain:read scope.

Resolution: Generate a new PAT with at least the domains.domain:read scope. Go to Authentication — PAT scopes.

Empty or unexpected JSON response

Symptom: The response is empty, missing fields, or returns an unexpected structure.

Cause: The domain parameter is malformed — missing the TLD, contains invalid characters, or uses an unsupported encoding.

Resolution:

• Use a fully-qualified domain name including the TLD: your-idea.com, not your-idea.
• IDN (internationalized) domains must use punycode A-label form.
• Check for invisible characters copied from other sources (zero-width spaces, smart quotes).

available: false for a domain you expected to be available

Symptom: The availability check returns false for a domain that appears unregistered.

Cause: The domain may be reserved, premium, or in a registry hold state that makes it unavailable through standard registration.

Resolution:

• The definitive field indicates whether the result came from a live registry check. If false, try again with optimizeFor=ACCURACY for a live check.
• Some TLDs reserve common words or short names. Try alternative TLDs.
• Premium domains may be available but at higher pricing — check the aftermarket.

Connection timeout or slow responses

Symptom: curl hangs or times out connecting to the API.

Cause: Network issues, firewall blocking HTTPS to external hosts, or the API is experiencing degraded performance.

Resolution:

• Test basic connectivity: curl -I https://api.godaddy.com
• Check your firewall allows outbound HTTPS (port 443) to api.godaddy.com.
• Add a timeout to your curl commands: curl --max-time 30 ...

Last updated on