# Build an API integration (https://developer.godaddy.com/en/docs/api-users/workflows/api-integration)

***

title: Build an API integration
description: End-to-end workflow — set up credentials, make authenticated calls, handle errors, and prepare for production.
agentNotes:
permissions: \["Any account"]
scopes: \["domains.domain:read (minimum for example calls in this guide)"]
rateLimit: "Rate-limited per credential per window. Go to /docs/api-users/rate-limits for current values."
idempotent: true
destructive: false
failureRecovery: "All calls in this guide are read-only. Safe to retry any failure. On 401, verify the token is exported correctly. On 429, implement exponential backoff with the Retry-After header."
related:
apis:

* title: "Domains v3 reference"
  href: "/docs/references/rest/domains/v3"
  guides:
* title: "Quickstart"
  href: "/docs/api-users/quickstart"
* title: "Authenticate"
  href: "/docs/api-users/auth"
* title: "Handle errors"
  href: "/docs/api-users/errors"
* title: "Rate limits"
  href: "/docs/api-users/rate-limits"

***

## 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](https://sso.godaddy.com/account/create/))
* 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](https://developer.godaddy.com/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:

   ```bash
   export GODADDY_PAT="<YOUR_GODADDY_PAT>"
   ```

Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) 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:

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

Go to the [quickstart](https://developer.godaddy.com/docs/api-users/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:

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

2. Implement error handling:

```js
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](https://developer.godaddy.com/docs/api-users/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](https://developer.godaddy.com/docs/api-users/rate-limits) for current values.

* Implement retry logic that respects the `retryAfterSec` field:

```js
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](https://developer.godaddy.com/docs/api-users/rate-limits) for the full strategy guide.

## Production readiness checklist

Before deploying to production, verify:

| Concern                 | Action                                                             |
| ----------------------- | ------------------------------------------------------------------ |
| **Credential security** | PAT stored in a secrets manager, never committed to source control |
| **Error handling**      | All expected error codes handled with appropriate user feedback    |
| **Rate limiting**       | Exponential backoff with jitter implemented                        |
| **Idempotency**         | Write operations use `Idempotency-Key` header where supported      |
| **Monitoring**          | Log `code` field from error responses for alerting                 |
| **Pagination**          | List operations use cursor pagination, not parallel fetches        |
| **Environment**         | Production PAT targeting `api.godaddy.com`                         |