DNSimple API Best Practices

Table of Contents

• Test in the Sandbox before production
• Handle pagination
• Use webhooks instead of polling
• Respect rate limits
• Have more questions?

Reliable DNSimple API integrations test in the Sandbox first, handle pagination, use webhooks instead of polling, and stay within rate limits. These practices apply whether you are working in the Sandbox or in production.

Test in the Sandbox before production

Develop and validate your integration against the DNSimple Sandbox before pointing it at production. The Sandbox is a fully functional copy of the DNSimple environment where API calls do not affect live domains, DNS records, or billing. Once your code works in the Sandbox, switching to production requires only a base URL and token change.

For a step-by-step setup guide, see Getting Started With the DNSimple Sandbox. For things to watch out for in the Sandbox specifically, see Sandbox Common Pitfalls.

Handle pagination

The DNSimple API paginates responses, returning up to 30 results per page by default (maximum 100). If you do not account for pagination, you will miss records when a response spans multiple pages. Always check the pagination object in the response and request subsequent pages until you have all results.

Request a specific page and page size with query parameters:

curl -H "Authorization: Bearer $DNSIMPLE_TOKEN" \
     -H "Accept: application/json" \
     "https://api.dnsimple.com/v2/$DNSIMPLE_ACCOUNT_ID/zones/example.com/records?page=1&per_page=100"

The response includes pagination metadata:

{
  "data": [...],
  "pagination": {
    "current_page": 1,
    "per_page": 100,
    "total_entries": 250,
    "total_pages": 3
  }
}

Loop through pages by incrementing the page parameter until current_page equals total_pages.

Use webhooks instead of polling

Rather than polling the API to detect changes, use DNSimple webhooks to react to events in real time. Webhooks reduce unnecessary API calls and ensure your integration responds promptly to domain registrations, DNS changes, and other events.

Register a webhook URL with your account:

curl -H "Authorization: Bearer $DNSIMPLE_TOKEN" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -X POST \
     -d '{"url":"https://your-app.example.com/webhooks/dnsimple"}' \
     https://api.dnsimple.com/v2/$DNSIMPLE_ACCOUNT_ID/webhooks

DNSimple sends an HTTP POST request to your URL whenever an event occurs. Your endpoint must respond with HTTP 200 to acknowledge receipt. DNSimple treats any other response as a failed delivery and retries it. See delivery attempts and retries in the developer documentation. For webhook configuration details, see Webhooks and API Events.

Respect rate limits

The DNSimple API enforces rate limits to protect service quality. The limit is set per account, and the default is 2,400 requests per hour. Every account token draws from the same limit. User tokens (OAuth and HTTP Basic) also draw from the account limit when they call an endpoint that includes an account ID in the path. When a user token calls an endpoint without an account ID, such as /v2/whoami, the limit is per user, at a fixed 2,400 requests per hour. Your account’s current limit, remaining requests, and reset time are on the API & Access page.

Domain availability checks have their own, lower limit of 60 requests per hour, separate from the account limit. Once you reach 60 checks, further checks fail until the hour resets, even if you still have requests left in your account limit. Do not use repeated availability checks to watch for a domain to expire. Drop catching is not allowed.

Check the rate limit headers in any API response to monitor your usage. Call an endpoint that includes your account ID, so the headers show your account’s limit:

curl -I -H "Authorization: Bearer $DNSIMPLE_TOKEN" \
     https://api.dnsimple.com/v2/$DNSIMPLE_ACCOUNT_ID/domains

The relevant headers are:

• X-RateLimit-Limit: maximum requests per hour
• X-RateLimit-Remaining: requests remaining in the current window
• X-RateLimit-Reset: Unix timestamp when the window resets

When you go over a limit, the API responds with 429 Too Many Requests. Design your integration to handle it: stop sending requests, and wait until the limit resets before you try again.

The rate limit headers only show your overall API limit. They do not show endpoint-specific limits, such as the limit on domain availability checks. If you reach the availability check limit, the API returns 429 with the message endpoint checkDomain quota exceeded, even though X-RateLimit-Remaining still shows requests left. In that case, the X-RateLimit-Reset time does not apply. The availability check limit resets one hour after the first check in the current window.

Have more questions?

If you have additional questions or need any assistance with the DNSimple API, contact support, and we’ll be happy to help. You can also read more about the DNSimple API.