Rate limits and errors
Error shape
Every error is JSON with an error field carrying a message meant for a human reading a log:
{ "error": "API key missing required scope: tests:read" }Branch on the status code, not on the message text — messages get clearer over time and are
not part of the v1 contract.
Status codes
| Code | Meaning | What to do |
|---|---|---|
200 | Success | — |
201 | Test created | — |
400 | Malformed request body | Fix the request; retrying will not help |
401 | Missing, malformed, expired or revoked key | Check the key; do not retry |
403 | Key lacks the scope, or the plan has no API | Issue a key with the scope, or upgrade the plan |
404 | No such test or report, or the token expired | Do not retry |
429 | Rate limited | Wait Retry-After seconds, then retry |
5xx | Our fault | Retry with backoff; if it persists, tell us |
A 404 on a report you just created usually means the token is right but the message has not
arrived. A test that exists but is unscored returns 200 with "status": "pending" — so 404 really does mean no such test.
Rate limits
Key-authenticated requests are limited per account, per minute, at your plan’s rate. The limit applies to the account, not to the individual key, so ten keys do not get ten times the budget.
Over the limit you get 429 with a Retry-After header in seconds:
HTTP/1.1 429 Too Many Requests
Retry-After: 6
Content-Type: application/json
{ "error": "API rate limit exceeded" }Honour Retry-After. It is calculated from your plan’s actual rate — on a 10/min plan the
next request slot is about six seconds away, so the header says 6 rather than a blanket minute.
Retrying sooner just consumes the limit again.
POST /v1/tests requires a key on this API. Tests can be run without an account from the
website, but not from api.deliversight.com.
Retrying safely
POST /v1/tests is not idempotent: each call allocates a new address and consumes quota from
your monthly test allowance. If a create request times out, check whether it succeeded before
retrying — a blind retry loop can burn a month’s quota quickly.
GET requests are safe to retry freely.