Troubleshoot DNSimple API Errors

Table of Contents

• 401 Authentication failed
• 403 Permission Denied
• 412 Feature not enabled
• 429 quota exceeded
• 429 endpoint checkDomain quota exceeded
• Some results are missing
• Have more questions?

Most DNSimple API errors come from the access token or from a rate limit. Find the status code and message in the error response, then go to the matching section below. For what each status code means, see API Errors.

401 Authentication failed

The API did not accept the access token. Check these causes in order:

• Wrong environment. A Sandbox token only works with api.sandbox.dnsimple.com, and a production token only works with api.dnsimple.com. Sending a Sandbox token to the production API returns 401 Authentication failed.
• Token disabled or deleted. A disabled token and a deleted token both return 401. Check the token list on the API & Access page of your account, or the User access tokens section of your user profile.
• Header format. Send the full token in the header Authorization: Bearer YOUR_TOKEN.

To test a token, call the whoami endpoint with the same host and header your integration uses:

curl -H "Authorization: Bearer $DNSIMPLE_TOKEN" \
     -H "Accept: application/json" \
     https://api.dnsimple.com/v2/whoami

A working account token returns the account. A working user token returns the user, with "account": null.

403 Permission Denied

A scoped access token does not have permission for the request. Only scoped account tokens return this error. User tokens and full-access account tokens are not limited by permission scopes.

The message names the permission the request needs, for example Permission Denied. Required Scope: zones:{zone_name}:write. The three parts are the resource type, the resources it covers (* means all of them), and the access level (read or write).

To fix it:

See API Access Token for how permission scopes work.

412 Feature not enabled

The account’s plan does not include a feature the request needs. The message names the feature.

A common case is Feature not enabled: scoped_access_tokens. Scoped access tokens are available on the Teams plan and higher. If an account moves to a plan without scoped tokens, its existing scoped tokens stop working. To fix it, change the account’s plan, or use a token with full access to the account.

429 quota exceeded

The account went over its hourly API rate limit. The default is 2,400 requests per hour, and every account access token on the account shares it. Creating another token does not add capacity.

To recover, stop sending requests until the time in the X-RateLimit-Reset header. The API Limits & Usage card on the API & Access page also shows when the limit resets.

To stay under the limit:

• Request 100 results per page. List endpoints return 30 results per page by default. Adding per_page=100 cuts the number of requests for large lists.
• Use webhooks instead of polling. A webhook notifies you when something changes, so you do not need to check repeatedly.
• Reduce parallel requests. Tools that make many requests at once, such as infrastructure-as-code runs across many zones, can use the hourly limit in minutes. Run fewer requests in parallel, or spread large runs over time. With the DNSimple Terraform provider, turn on the prefetch argument so it reads zone records in fewer requests.

See DNSimple API Best Practices for more.

429 endpoint checkDomain quota exceeded

Domain availability checks have their own limit of 60 per hour per account, separate from the hourly limit. The X-RateLimit-* headers do not describe this limit, so they can show requests remaining while domain checks are rejected.

Wait an hour, then spread checks out over time. DNSimple does not allow repeated availability checks to watch for a domain to expire. See Can I use DNSimple for drop catching?

Some results are missing

If a list request returns fewer domains, zones, or records than you expect, check these two causes:

• Pagination. List endpoints return 30 results per page by default and 100 at most. Check the pagination object in the response. If total_pages is greater than 1, request the next pages with the page parameter.
• Token scope. A scoped access token limited to specific domains or zones only lists those. The /domains and /zones endpoints do not return anything outside the token’s permissions, and do not return an error either. Check the token’s permissions on the API & Access page.

Have more questions?

If you have additional questions or need any assistance with the DNSimple API, contact support, and we will be happy to help.