Errors and rate limits
Problem documents
Section titled “Problem documents”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.
Concurrency: ETag and If-Match
Section titled “Concurrency: ETag and If-Match”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.
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}}'Pagination
Section titled “Pagination”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.
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).
Idempotency keys
Section titled “Idempotency keys”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.
Log query results
Section titled “Log query results”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.
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.
Log query limits
Section titled “Log query limits”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.
Live log stream
Section titled “Live log stream”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: rowswithid: <cursor>and, asdata, a query result holding the new rows. The first event carries the latest rows (up tolimit) unless you resume. Events are sent only when there are rows.event: errorwith a problem asdata: a failure while streaming. The stream goes on after a transient one (node_offline,node_timeout, a 5xx) and ends after any other.event: partialwith{"partial": true, "partial_reason": "node_reconnecting"}: a poll came back partial with no rows (the node is reconnecting). Sent once until a complete poll;rowsevents carry their ownpartialflag.- a
: heartbeatcomment 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.
curl -N -H "Authorization: Bearer $OPDNS_TOKEN" \ 'https://api.opdns.io/v1/profiles/abc123/logs/stream?status=blocked'Logs from a node
Section titled “Logs from a node”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).
List reports
Section titled “List reports”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.
Rate limits
Section titled “Rate limits”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: 120RateLimit-Remaining: 0RateLimit-Reset: 23RateLimit-Policy: 120;w=60Retry-After: 23Past 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).
Dashboard error reports
Section titled “Dashboard error reports”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).