Errors - PanelDNS

Validation errors (422)

When request fields fail validation, Laravel’s standard validation-exception response is returned — a message summary plus a errors object keyed by field, each holding an array of failure messages. This does not use the {"ok": ..., "error": ...} envelope used elsewhere in this API:

{
  "message": "The name field is required.",
  "errors": {
    "name": ["The name field is required."]
  }
}

Authentication errors (401)

A missing, revoked, or expired token fails Sanctum authentication before any controller runs, so it renders with Laravel’s default unauthenticated response — not the {"ok": ..., "error": ...} envelope used elsewhere:

{ "message": "Unauthenticated." }

Causes:

Token missing from Authorization header
Token revoked or expired

A request from an IP outside the token’s allowlist is not a 401 — it returns 403 with a different shape. See below.

IP allowlist errors (403)

{ "ok": false, "message": "This token is restricted to specific IP addresses.", "code": 403 }

Note this specific error uses the key message, not error, unlike other error responses in this API.

Scope / permission errors (403)

{ "ok": false, "error": "Scope 'zones:write' required.", "code": 403 }

For the Reseller API, each endpoint requires one of six scopes: zones:read, zones:write, records:read, records:write, sub_clients:read, sub_clients:write. Token scopes are set at creation time and cannot be changed — create a new token with the required scope.

Not found errors (404)

{ "ok": false, "error": "Not found.", "code": 404 }

This generic message is returned when a zone, record, or sub-client ID in the URL path doesn’t exist or belongs to a different org — intentionally the same message in every case so a caller cannot use it to enumerate IDs belonging to other orgs. One exception: Create Zone returns a specific "Sub-client not found." message (still 404) when the sub_client_id in the request body doesn’t belong to your org.

Rate limiting (429)

{ "ok": false, "error": "Too Many Requests.", "code": 429 }

API tier	Limit
Platform API	60 req / min per IP
Reseller API	Per plan: Starter 60, Pro 300, Agency 1,200 req / min per org (shared across all of that org’s tokens)
Failed authentication	60 failed attempts / min per IP (successful requests don’t count)

Retry after the Retry-After response header value (seconds).

Provider errors (502)

{ "ok": false, "error": "Cloudflare: failed to create record (status 400): ...", "code": 502 }

The DNS provider returned an error. The error string contains the provider’s message. Check:

The record content is valid for the type
The zone exists on the provider (may need re-syncing)
The provider’s API is reachable from your PanelDNS server

​Validation errors (422)

​Authentication errors (401)

​IP allowlist errors (403)

​Scope / permission errors (403)

​Not found errors (404)

​Rate limiting (429)

​Provider errors (502)

Validation errors (422)

Authentication errors (401)

IP allowlist errors (403)

Scope / permission errors (403)

Not found errors (404)

Rate limiting (429)

Provider errors (502)