Error reference
Base URLhttps://planet-project.click/api/v1
AccessBearer token + whitelist IP
Rate limit10 RPS per token
VersionErrors v1
UpdatedUpdated 15 May 2026
Error reference

PlanetDomains API error reference

A compact guide to the errors you actually meet in trading, DNS, whitelist, and webhook-adjacent flows. Keep it close while you wire retries, dashboards, and alerting.

Back to docs OpenAPI JSON Webhook guide

Overview

Classify failures fast
The cleanest mental model is simple: 401/403 mean access, 404/422 mean caller data or ownership, 409 means state/config mismatch, and 429 means you need to slow down.

Access and token

Bearer + whitelist
401
unauthorized

The token is invalid, revoked, or already rotated.

Error
WhenWhen the bearer token cannot be found or was already revoked.
MeaningYou need a fresh token or the currently active one.
Show detailsparams / body / response / notes

Related endpoints

GET /api/v1/account
A quick token smoke-check.
POST /api/v1/domains/register
A common working method where the issue shows up immediately.

Operational notes

  • Check whether the token was rotated in Profile -> API.
  • Make sure the Authorization header is sent intact.
403
forbidden

Whitelist is empty or the server IP did not match.

Error
WhenWhen the token is valid but the current IP is not allowed.
MeaningWorking API access is closed until whitelist is fixed.
Show detailsparams / body / response / notes

Related endpoints

GET /api/v1/account
Access check after fixing whitelist.

Operational notes

  • Add the server IP to Whitelist in the bot.
  • If a proxy is involved, verify the real client IP.

Trading errors

404 / 409 / 422 / batch items
404
domain_not_found

The domain was not found in your account or by the requested name.

Error
WhenWhen detail, renew, DNS, or NS target a non-existent domain.
MeaningThe caller passed the wrong domain name or is using the wrong user context.
Show detailsparams / body / response / notes

Related endpoints

GET /api/v1/domains
List the user's domains.
GET /api/v1/domains/{domain}
Get the domain details.

Operational notes

  • Check the user domain list first.
  • Do not assume search alone means the domain is already in the account.
409
cloudflare_not_configured

The Cloudflare profile is missing, disabled, or unsuitable for the domain.

Error
WhenWhen bind is called without a valid cloudflare_profile_key.
MeaningYou need to fix the profile in the bot or choose another one.
Show detailsparams / body / response / notes

Related endpoints

POST /api/v1/domains/{domain}/cloudflare/bind
The bind operation itself.

Operational notes

  • Check Cloudflare in Configurator.
  • Do not mix bind with an unprepared profile.
422
validation_error

The payload failed validation or the requested config is incompatible.

Error
WhenWhen the caller passes bad DNS records, nameservers, years, or config overrides.
MeaningThis is a client-side issue, not an external provider failure.
Show detailsparams / body / response / notes

Related endpoints

PUT /api/v1/domains/{domain}/dns
A common source of DNS record validation errors.
POST /api/v1/domains/register
Registration with config override.

Operational notes

  • Show the user the exact field that failed validation.
  • Do not do a blind retry: fix the payload first.

Infrastructure

Cloudflare and provider steps
500
provider_error

An external provider or an intermediate step could not complete the operation.

Error
WhenWhen a downstream service returns an unexpected error or timeout.
MeaningYou need log-level diagnosis and sometimes a retry with backoff.
Show detailsparams / body / response / notes

Related endpoints

POST /api/v1/domains/register
Registration often crosses external provider steps.
POST /api/v1/domains/{domain}/cloudflare/bind
Bind also depends on an external side.

Operational notes

  • Check the related provider logs or webhook delivery history.
  • Do not hammer immediate retries after a 500.

Limits and retry

10 RPS baseline
429
rate_limited

The token hit the rate guard and must slow down.

Error
WhenWhen a token runs too fast and exceeds the expected RPS.
MeaningThe token is temporarily blocked to protect the API and provider path.
Show detailsparams / body / response / notes

Related endpoints

POST /api/v1/domains/register/batch
The preferred path for bulk trading.
POST /api/v1/domains/renew/batch
Batch renew instead of many single calls.

Operational notes

  • Add queueing or backoff on the client.
  • For bulk flows, use batch first.

What to do next

Operational checklist
  1. Separate access issues, payload issues, and pacing issues first.
  2. Surface 422 and batch-item failures back to the panel as precise hints, not generic failures.
  3. A 409 almost always means the state or config must be fixed first.
  4. A 429 is solved by backoff and batch logic, not by a harder retry storm.
  5. If the failure is webhook-related, open delivery history and inspect the latest attempt.