# 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.
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/search-domains"
  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 <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](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 ...`