NewHost Docs

Errors, limits & paging

Errors

Failed requests return a non-2xx status and a JSON body in the same shape every time:

{
  "error": {
    "message": "API key is missing the 'deploy' scope",
    "code": "insufficient_scope",
    "status": 403
  }
}
StatusCodeMeaning
400invalid_requestThe body or query is missing or invalid. The message says which field.
401unauthorizedNo key, an unknown key, or a revoked or expired key.
402plan_limitYour plan does not allow this, e.g. one app too many. Upgrade and retry.
403forbidden / insufficient_scopeThe key lacks the endpoint's scope, or a public key was used from a disallowed origin.
404not_foundThe resource does not exist or belongs to another account.
409conflictIt clashes with the current state, e.g. a deployment is already running.
409idempotency_conflictThe Idempotency-Key was already used with a different request. Use a new key for a new request; see Authentication.
409idempotency_in_progressA request with this Idempotency-Key is still running. Retry with the same key in a few seconds to get its answer; see Authentication.
409record_existsA DNS record with that name and type already exists in the zone with another value. Edit or delete it first.
429rate_limitedToo many requests. Wait for Retry-After seconds.
502 / 503registry_unavailableThe domain registry could not answer, e.g. for a domain search. Nothing was changed; retry later.
502upstream_unavailableA server could not complete the change, e.g. removing an app's site, so the app or preview was not deleted. Retry later.
500 / 502 / 503server_errorA problem on our side or at an upstream (registry, server). Safe to retry with backoff.

Branch on code, not on message. For 4xx errors the message says what to fix. For 5xx errors it is a general text (on the AI gateway with your own provider key, your provider's message): the details stay in our logs.

Rate limits

Limits are per key, over a rolling minute:

  • Secret keys: 120 requests per minute.
  • Public keys: 30 requests per minute.
  • Domain search (GET /v1/domains/check): also 20 searches per minute per key, within a limit shared by all of NewHost's domain searches. Past either you get 429 with the code rate_limited; try again a minute later.

Every response tells you where you stand:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 1790000000   # Unix time the window resets

When you hit the limit you get 429 with a Retry-After header. Back off and retry after that many seconds.

Paging

List endpoints take limit (1-100, default 50) and offset, and return has_more:

GET https://api.newhost.co.za/v1/invoices?limit=100&offset=100

{ "data": [ ... ], "has_more": true }

Fetch every page (Node.js)

async function all(path) {
  const out = [];
  for (let offset = 0; ; offset += 100) {
    const res = await fetch(`https://api.newhost.co.za/v1${path}?limit=100&offset=${offset}`, {
      headers: { Authorization: `Bearer ${process.env.NEWHOST_SECRET_KEY}` },
    });
    const page = await res.json();
    out.push(...page.data);
    if (!page.has_more) return out;
  }
}

Formats

  • Money is a string with two decimals in rand (ZAR), e.g. "99.99". Global Software Services (Pty) Ltd, the company behind NewHost, is not registered for VAT, so no VAT is added: the price shown is the full amount you pay, and every vat field is "0.00".
  • Dates are ISO 8601 in UTC, e.g. 2026-09-24T10:15:00.000Z.
  • Send request bodies as JSON with Content-Type: application/json.