Helstify — Errors and limits

How answers look

Requests: Send JSON bodies with Content-Type: application/json.
Responses: JSON, except the browser endpoints, which answer in plain text.
Paths: File paths start at the site's home folder, never the server's root.
Time: Timestamps are ISO 8601 in UTC. File times are Unix seconds.
Long jobs: Council turns and backups answer 202 with something to check back on.

Errors

Status	Code	Means
400	`bad_request`	The request could not be read. Send JSON with Content-Type: application/json.
401	`unauthenticated`	No key, a malformed key, or a revoked or expired one.
403	`missing_scope`	The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission).
404	`not_found`	No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account.
409	`conflict`	The business is read-only, asleep, or has no running server (see reason).
422	`validation`	A field is missing or wrong. message says what, and errors lists each field.
429	`rate_limited`	Too many requests for this key this minute. Wait Retry-After seconds.
502	`upstream`	A server behind the business (the mail server, the container) did not answer properly. Safe to retry.

An error looks like this:

{
    "ok": false,
    "error": "This API key does not have the \"dns:write\" scope.",
    "code": "missing_scope",
    "scope": "dns:write"
}

Rate limits

Each key has its own limit, chosen when you make it: 60, 120, 300 or 600 requests a minute. Running a tool is held to 40 a minute and starting a council turn to 20. Every answer says where you stand.

X-RateLimit-Limit: Requests this key may make each minute.
X-RateLimit-Remaining: How many are left this minute.
Retry-After: After a 429, how many seconds to wait.