# Build an API integration (https://developer.godaddy.com/en/docs/api-users/workflows/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.

<Mermaid
  chart="
graph TD
A[Create account] --> B[Generate PAT]
B --> C[Make first call]
C --> D[Handle errors]
D --> E[Add rate limit handling]
E --> F[Production readiness]

style A fill:#e3f2fd
style F fill:#c8e6c9
"
/>

## 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`                         |