Skip to content
Log inDashboard

Errors and rate limits

Errors are RFC 9457 problem documents (application/problem+json) with a stable machine code. Match on code, not on title or detail.

{
"type": "https://opdns.io/problems/validation_failed",
"title": "Validation failed",
"status": 422,
"code": "validation_failed",
"errors": [{ "field": "settings.retention_days", "message": "must be 1 to 90" }],
"request_id": "…"
}

Include request_id when you report a problem. The full list of codes is the Problem schema in the reference.

Status Common codes
400 bad_request, body_too_large, bad_if_match, invalid_token, token_expired, token_used, invalid_cursor, bad_idempotency_key
401 unauthenticated, second_factor_required, invalid_recovery_code, node_revoked
403 insufficient_scope, session_required, csrf_rejected, reauth_required, mfa_enrolment_required, mfa_required, email_unverified
404 not_found (also for another organisation’s resources)
409 ip_conflict, email_taken, idempotency_key_reused, idempotency_in_progress, profile_not_empty, profile_suspended, node_token_superseded
412 version_mismatch
422 validation_failed, unknown_list, too_many_rules, password_too_short, password_too_long, range_too_large, query_too_expensive
429 rate_limited, login_unlock_required, too_many_streams, too_many_reports, too_many_queries
501 not_implemented, shape_unsupported
502, 503, 504 node_error; node_offline, node_busy, relay_unavailable, server_busy; node_timeout, query_timeout

A new password (sign-up, change, reset, recovery) of fewer than 10 or more than 256 Unicode code points is 422 password_too_short or password_too_long, with the password field in errors; when other fields are invalid too, the answer is validation_failed listing them all. There is no other password rule.

Every JSON request body is checked against its schema in the reference before the operation runs: a missing required field, a wrong type, a value outside an enum or a length or range limit, or a malformed email address, UUID, date-time or IPv4 address is 422 validation_failed (400 on the few sign-in operations that document no 422), with one entry per field in errors. Nested fields are named with dots and indexes, such as deny[2].pattern. A field the schema does not have is 400 bad_request, and so is a body that is not JSON.

409 profile_suspended answers a change to a profile opdns has suspended: its settings, rules, lists, linked IPs, devices, deletion and new nodes. Reads still work. The profile’s suspended field says so in advance; see Suspended profiles.

Every profile resource returns its version as a strong ETag ("3"). Send it back as If-Match on a write; if someone changed the profile in between, the write fails with 412 version_mismatch and nothing changes. Omit If-Match to write unconditionally. Every successful write bumps the version and publishes the whole profile to the resolvers.

Terminal window
curl -X PATCH https://api.opdns.io/v1/profiles/abc123 \
-H "Authorization: Bearer $OPDNS_TOKEN" \
-H 'If-Match: "3"' -H 'Content-Type: application/json' \
-d '{"settings":{"retention_days":7}}'

Every list endpoint is cursor-paginated. Send limit (default 50, at most 200) and, for the next page, cursor set to the previous page’s next_cursor; next_cursor is null on the last page. The order is stable, so rows created while you page are never repeated or skipped before the cursor. Cursors are opaque: a modified one is 400 invalid_cursor.

Terminal window
curl -H "Authorization: Bearer $OPDNS_TOKEN" \
'https://api.opdns.io/v1/profiles?limit=100&cursor=…'

Log queries page the same way, with their own limit (at most 1,000 rows).

POSTs that create something (profiles, tokens, linked IPs, nodes, exports, list reports) accept an Idempotency-Key header, any unique string such as a UUID. Repeating the request with the same key and the same body within 24 hours replays the first successful answer, with Idempotent-Replayed: true, instead of creating a second one. So a script can retry a request whose answer it never received.

Situation Answer
same key, same request, first one succeeded the first answer again, Idempotent-Replayed: true
same key, first one still running 409 idempotency_in_progress with Retry-After; retry with the same key
same key, different request 409 idempotency_key_reused
first one failed nothing is stored; the key can be used again

Keys are per account.

GET /v1/profiles/{id}/logs and /analytics/{shape} answer a QueryResult: columns, rows, source (clickhouse for the cloud’s log database, node for your self-hosted node, or none), next_cursor, and partial.

Log rows (tail and search) carry the stored columns (ts, source, pop, node, profile_id, device_id, device_name, client_ip, transport, qname, qtype, status, reason_list_id, reason_rule, rcode, dnssec_validated, cache_hit, latency_us, answer_ips) and four derived ones, computed the same way for cloud and node results, whatever the node’s version:

Column Holds
reason the list name when a list decided, else the rule or operator text as stored (denylist: *.example.com, rewrite: =nas.home, legal_order LO-17); empty when domain logging blanked a rule
reason_code list, rule, operator:<code> (legal_order, abuse, csam), rewrite, or none for allowed and failed queries
ede_code the Extended DNS Error the client received: 15 for operator blocks, 17 for every other block, 0 otherwise (a failed upstream’s EDE is not recorded)
ede_text the EDE extra text: the reason of a block

The top_reasons analytics shape groups queries by what decided them: reason_code, list_id (for list only), reason and count, most frequent first. Without a status filter it counts blocked and rewritten queries. A self-hosted node older than this shape answers 501 shape_unsupported.

The destinations shape groups allowed queries by answer address: ip, count, and since API 0.2.0 two more columns:

Column Holds
country the ISO 3166-1 alpha-2 code of the address from the server’s GeoIP database; "" when unknown, when the address is not public, or when the deployment has no database
owner the company whose address it is: google, apple, meta, amazon, microsoft, or the CDNs cloudflare, akamai, fastly; "" for any other

The API adds both columns to answers that lack them (a node older than this change) and fills an empty country from its own database, so a relayed answer has countries even though nodes have none. When the database’s licence asks for credit, geoip_attribution in GET /v1/meta holds the notice to show next to the countries. Where both come from: What ingest adds.

The top_owners shape counts queries by the company they reached: owner and count, most first, ties by owner. A query’s owner is its name’s (a curated list of domain suffixes: youtube.com is Google’s), or else its first classified answer address’s; queries with neither are left out. It has no default status filter. A node older than this shape answers 501 shape_unsupported.

The top_pops shape (API 0.5.0) counts queries by the PoP that answered them: pop and count, most first, ties by pop. pop is the PoP’s short id (ams), or node for queries a self-hosted node answered itself; records without a PoP are left out. The default limit is 10, at most 100, and there is no default status filter. A node older than this shape answers 501 shape_unsupported.

Terminal window
curl -H "Authorization: Bearer $OPDNS_TOKEN" \
'https://api.opdns.io/v1/profiles/abc123/analytics/top_pops?limit=20'

To name and place the ids, GET /v1/pops (no authentication) lists the deployment’s PoP catalogue, sorted by id: id, name (the label to show, the city), city, region (the subdivision code, when there is one), country (ISO 3166-1 alpha-2), lat and lon (WGS 84 degrees), status and servers. status follows what the PoP’s servers report every 30 seconds: serving (every server in service answers), degraded (some do), down (none does, or none has been heard from for 5 minutes) or planned (not in service yet); health_updated_at is when a server of the PoP was last heard from, and each server lists its own state (announced, withdrawn, or unknown when not heard from lately). It may be cached for 15 seconds (Cache-Control: public, max-age=15); a deployment without PoP locations answers an empty array.

[
{ "id": "ewr", "name": "Secaucus", "city": "Secaucus", "country": "US",
"region": "NJ", "lat": 40.777664, "lon": -74.071382, "status": "serving",
"health_updated_at": "2026-10-01T21:40:12Z",
"servers": [
{ "name": "pop-ewr-1", "state": "announced", "healthy": true,
"sessions": { "up": 2, "total": 2 }, "last_seen": "2026-10-01T21:40:12Z" },
{ "name": "pop-ewr-2", "state": "announced", "healthy": true,
"sessions": { "up": 2, "total": 2 }, "last_seen": "2026-10-01T21:40:05Z" }
] }
]

partial is true when a node answered with fewer rows than asked (partial_reason timeout, near its query deadline, or overload), or when a self-hosted profile’s node is between link sessions (node_reconnecting, no rows; a tail keeps its cursor). The rows present are correct.

Every log and analytics query passes the same guardrails before any store is read, whether the cloud’s log database or your self-hosted node answers it.

Range. Each shape covers at most a fixed time range:

Shapes Longest from..to
search, top_devices, destinations, top_pops (read every row of the range) 31 days
counts_by_status, timeline, top_domains, top_blocked, top_reasons, top_owners (read hourly totals) 400 days
tail (the newest rows under limit) no limit

A wider range is 422 range_too_large, with from named in errors. A query without from is not refused: its range starts that long before to (or now), so a bare search covers the last 31 days. The dashboard’s widest preset, 30 days, fits every shape. Cloud logs are kept at most 90 days anyway.

{
"type": "https://opdns.io/problems/range_too_large",
"status": 422,
"code": "range_too_large",
"detail": "search queries cover at most 31 days; narrow from and to",
"errors": [{ "field": "from", "message": "at most 31 days before to" }]
}

Cost and concurrency. Queries draw on a budget per organisation: two units per day of range for a query that reads raw rows (the 31-day shapes, and any shape filtered by more than time), one unit per week of range for one that reads hourly totals, one unit for a tail. The budget is refilled at 1,200 units a minute (about five 30-day Analytics page loads). At most four queries of an organisation run at once; another one waits up to five seconds for a slot. A query over budget, or still without a slot after five seconds, is 429 too_many_queries with Retry-After (seconds, also retry_after in the body): wait that long and retry.

Expensive queries. A cloud query that would read more rows (500 million) or memory (2 GiB) than one query may is stopped and answered 422 query_too_expensive: narrow the range or add filters, retrying the same query will not help.

These limits are the same on every plan today. They are counted per API server, not across the whole service.

GET /v1/profiles/{id}/logs/stream (scope logs:read) is the live tail as server-sent events, with the filters of a tail log query:

  • event: rows with id: <cursor> and, as data, a query result holding the new rows. The first event carries the latest rows (up to limit) unless you resume. Events are sent only when there are rows.
  • event: error with a problem as data: a failure while streaming. The stream goes on after a transient one (node_offline, node_timeout, a 5xx) and ends after any other.
  • event: partial with {"partial": true, "partial_reason": "node_reconnecting"}: a poll came back partial with no rows (the node is reconnecting). Sent once until a complete poll; rows events carry their own partial flag.
  • a : heartbeat comment every 15 seconds. Each heartbeat re-checks your credential and the profile: a revoked session or token, or a deleted profile, ends the stream.

Reconnect with Last-Event-ID (browsers’ EventSource does it by itself) or ?cursor= set to the last event id to resume without gaps or repeats. The server checks the log destination every second and ends a stream after an hour; reconnect. An account may hold 4 streams at once per API server; beyond that the answer is 429 too_many_streams, and polling GET /v1/profiles/{id}/logs?mode=tail with cursor is the fallback the dashboard uses.

Terminal window
curl -N -H "Authorization: Bearer $OPDNS_TOKEN" \
'https://api.opdns.io/v1/profiles/abc123/logs/stream?status=blocked'

Log and analytics queries are answered from the profile’s log destination. For a self-hosted destination they are relayed to the node, which can be offline (503 node_offline with Retry-After), busy (503 node_busy, at most 4 queries in flight per node), slow (504 node_timeout, 10 seconds) or too old for a query shape (501 shape_unsupported).

POST /v1/profiles/{id}/list-reports (scope profiles:write) reports a domain that list list_id blocks but should not (kind false_positive) or misses (false_negative), with an optional note of up to 500 characters. The answer is 202 with the report’s id. The domain is stored in lower case without a trailing dot, with the list’s catalogue version at the time. An account may send 20 reports in 24 hours; the 21st is 429 too_many_reports with Retry-After. GET on the same path (scope profiles:read) lists the profile’s reports, newest first, with their status (open, accepted, rejected), the maintainers’ resolution_note and triage_due_at, the maintainers’ target for an answer: two business days (Monday to Friday, UTC) after the report. When the maintainers accept or reject a report, the reporter gets an email with the outcome and their note. Accepting a report changes no list by itself; see Report a wrong block or a miss.

Unauthenticated routes (sign-up, sign-in, the catalogue, enrolment, DDNS) are limited per client network (an IPv6 /64 or an IPv4 address; sign-in also per /48 or /24) and answer 429 rate_limited with Retry-After (seconds, repeated as retry_after in the body).

Password sign-in has two more limits, counted on every server together: after 20 failed attempts on an address within an hour, or 10 wrong second-factor codes on an account, POST /v1/auth/login answers 429 login_unlock_required and the address is emailed a sign-in link; send the link’s token as unlock_token with the password. Passkey sign-in is not limited this way. A route that checks a password may answer 503 server_busy with Retry-After when the server is saturated.

Requests with an API token are limited per organisation: every token of every member counts against one budget, the plan’s API requests per minute (api_requests_per_minute in GET /v1/account/plan, and each plan’s number on the pricing page). The budget is counted in fixed one-minute windows, the same on every server that answers you. Dashboard sessions do not count.

Every response to a token says where you stand, with the fields of the IETF RateLimit header draft:

Header Value
RateLimit-Limit the plan’s requests per window
RateLimit-Remaining requests left to the organisation in this window
RateLimit-Reset seconds until this window ends
RateLimit-Policy the policy, <limit>;w=60
RateLimit-Limit: 120
RateLimit-Remaining: 0
RateLimit-Reset: 23
RateLimit-Policy: 120;w=60
Retry-After: 23

Past the limit the answer is 429 rate_limited with Retry-After (the same seconds as RateLimit-Reset). Wait that long and retry; spread requests across the window rather than sending them in bursts, and give each script its own token so the audit log tells them apart (they still share the budget).

POST /v1/client-errors (a session, or a token with account:read) stores a scrubbed error report from the dashboard: message, stack, route, version and user agent, at most 32 KiB, 10 reports a minute per account. Reports are kept 30 days and deleted with the account. The dashboard’s own reporting can be turned off per browser (Error reports).