Build an API integration

Overview

This workflow takes you from zero to a production-ready API integration. It covers credential setup, your first call, error handling patterns, and the operational considerations for running in production.

Prerequisites

The following prerequisites are required before you build an API integration:

• A GoDaddy account (create one at sso.godaddy.com)
• A terminal with curl, or Node.js / Python installed

Generate a Personal Access Token

The following procedure generates a Personal Access Token (PAT) for authenticating API calls.

1. Sign in to the Personal Access Token page.

2. Click + Generate Token.

3. Select the scopes your integration needs (at minimum, domains.domain:read for read operations).

4. Copy the token immediately (it only displays once).

5. Export the credential:

   export GODADDY_PAT="<YOUR_GODADDY_PAT>"

Go to Authentication for the full scope reference and environment guidance.

Make your first authenticated call

The following procedure verifies your token works with a simple availability check. A successful response returns JSON with available, prices, and other fields. If you get a 401, check that the token is correctly set in the environment variable.

• Run the request:

curl -s "https://api.godaddy.com/v3/domains/check-availability?domain=example-test.com" \
  -H "Authorization: Bearer $GODADDY_PAT"

Go to the quickstart for a detailed walkthrough of this call.

Handle errors gracefully

The following procedure implements error handling for API responses. Every error response follows the same envelope. Match on code, not message. Build a switch/match statement for the codes you expect.

1. Examine the error shape:

{
  "code": "STABLE_ERROR_CODE",
  "message": "Human-readable description",
  "fields": []
}

2. Implement error handling:

const res = await fetch(url, { headers });
if (!res.ok) {
  const err = await res.json();
  switch (err.code) {
    case "QUOTA_EXCEEDED":
      await sleep(err.retryAfterSec * 1000);
      return retry(url, headers);
    case "UNAUTHORIZED":
      throw new Error("Token expired or invalid");
    default:
      throw new Error(`API error: ${err.code}`);
  }
}

Go to Handle errors for the full status code reference and retry semantics.

Add rate limit handling

When you apply rate limiting use the following strategies to stay under the limit:

• Use bulk endpoints where available (e.g., POST /v1/domains/available for batch checks)
• Cache availability results briefly when definitive: false
• Use cursor pagination instead of parallel page-walks

The following procedure adds rate limit handling to your integration. The API enforces a per-credential, windowed rate limit — go to Rate limits for current values.

• Implement retry logic that respects the retryAfterSec field:

async function callWithRetry(url, headers, attempts = 3) {
  for (let i = 0; i < attempts; i++) {
    const res = await fetch(url, { headers });
    if (res.status !== 429) return res;

    const { retryAfterSec } = await res.json();
    const jitter = Math.random() * 1000;
    await new Promise(r => setTimeout(r, retryAfterSec * 1000 + jitter));
  }
  throw new Error("Rate limit retries exhausted");
}

Go to Handle rate limits for the full strategy guide.

Production readiness checklist

Before deploying to production, verify:

Last updated on