# Troubleshoot your first API call (https://developer.godaddy.com/en/docs/api-users/troubleshoot/first-call)

---
title: Troubleshoot your first API call
description: >-
  Common errors when making your first call to the GoDaddy Domains API, with
  causes and resolutions.
keywords: >-
  Could not resolve host api.godaddy.com, echo GODADDY_PAT, HTTPS_PROXY curl
  proxy, curl --max-time timeout, definitive field optimizeFor ACCURACY,
  domains.domain:read 403, first API call 401, punycode domain encoding
agentNotes:
  scopes:
    - 'domains.domain:read'
  failureRecovery: >-
    Diagnostic page. All operations mentioned are read-only and safe to retry.
    On 401, verify token. On 403, check scopes. On timeout, check network.
faqItems:
  - question: Why does curl say 'Could not resolve host' for api.godaddy.com?
    answer: >-
      DNS can't resolve the API hostname. Verify internet connectivity, check
      corporate proxy settings (--proxy flag or HTTPS_PROXY), or disconnect VPN
      to rule out DNS filtering.
  - question: Why do I get 401 Unauthorized on my first API call?
    answer: >-
      The Authorization header is missing or the token value is wrong. Confirm
      your env var is set (echo $GODADDY_PAT), verify the format is 'Bearer
      {token}' with no extra quotes, and ensure you exported it in the same
      shell session.
  - question: Why does the availability check return 403 Forbidden?
    answer: >-
      Your token doesn't have the domains.domain:read scope. Generate a new PAT
      with at least the domains.domain:read scope.
  - question: Why is the JSON response empty or unexpected?
    answer: >-
      The domain parameter is likely malformed — missing the TLD, containing
      invalid characters, or using unsupported encoding. Use a fully-qualified
      domain name like 'your-idea.com' and ensure no invisible characters are
      present.
  - question: >-
      Why does the availability check say a domain is unavailable when it
      appears unregistered?
    answer: >-
      The domain may be reserved, premium, or in a registry hold state. Check
      the 'definitive' field — if false, retry with optimizeFor=ACCURACY for a
      live registry check. Some TLDs reserve common words.
  - question: Why is the API connection timing out?
    answer: >-
      Network issues, firewall blocking HTTPS to external hosts, or API degraded
      performance. Test connectivity with 'curl -I https://api.godaddy.com',
      ensure port 443 is open, and add --max-time 30 to your curl commands.
related:
  guides:
    - title: Make your first call
      href: /docs/api-users/quickstart
    - title: Troubleshoot authentication
      href: /docs/api-users/troubleshoot/authentication
    - title: Search domain availability
      href: /docs/api-users/domains/search
  concepts:
    - title: Error handling
      href: /docs/api-users/errors
    - title: Rate limits
      href: /docs/api-users/rate-limits
---

## Overview

This page covers errors you're likely to encounter during your first API calls. If you're getting started, go to the [quickstart](https://developer.godaddy.com/docs/api-users/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 <GODADDY_PAT>` — 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](https://developer.godaddy.com/docs/api-users/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](https://developer.godaddy.com/docs/api-users/auth#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 ...`