Errors

Every error is application/problem+json, following RFC 9457. Here is a 403 for a missing scope, byte for byte:

{
  "type": "https://docs.vitalsentinel.com/api/errors/insufficient-scope",
  "title": "Insufficient scope",
  "status": 403,
  "detail": "This credential does not have the 'read:overview' scope, which this endpoint requires. Create a new credential with that scope, or ask a workspace admin to grant it.",
  "instance": "/api/public/v1/domains/9c2f4d18-5e6a-4b70-8c19-2d3f5a7b9e04/overview",
  "request_id": "3f9a1c22-7b48-4e0d-96a1-5c8b2d7e4f10",
  "required_scope": "read:overview",
  "granted_scopes": ["read:domains"]
}

Several problems carry structured extras alongside the prose, so a client rarely has to parse a sentence:

The OAuth endpoints are the one exception to all of this: POST /oauth/token returns RFC 6749 errors instead. See Authentication.

The catalog

Every type is https://docs.vitalsentinel.com/api/errors/ followed by a suffix. These are the base families:

Many operations return a more specific suffix

A 404 from a CrUX endpoint is crux-url-not-found, not not-found. A 401 caused by an IP allowlist is ip-not-allowed, not invalid-credential. There are roughly forty of these.

The specialization is systematic, so you do not need the full list:

The rule for a client: switch on the HTTP status first, then on the suffix only where you handle a case specifically. An unrecognized suffix should fall back to its status family rather than to an error path.

kind = problem["type"].rsplit("/", 1)[-1]

if response.status_code == 404:
    # Every *-not-found narrows this. Treat them all as "not there, or not visible to me".
    return None
if response.status_code == 401:
    # ip-not-allowed is the one worth naming: the credential is fine, the network is not.
    raise BadCredential(hint="check the IP allowlist" if kind == "ip-not-allowed" else None)

New suffixes are additive and can appear at any time. See Versioning.

Two 403s that are not the same problem

insufficient-scope and insufficient-role both return 403, and telling them apart is the difference between a client that recovers and one that retries forever.

An agent that cannot distinguish them will keep minting credentials that fail the same way. See Scopes for the underlying rule.

Why 404 and not 403

When a credential's workspace access does not cover a resource that exists, the API returns 404, not 403. The two cases are deliberately indistinguishable.

Confirming that a resource exists but is not yours turns the endpoint into an identifier-guessing oracle. If you are getting an unexpected 404 on an identifier you are sure is right, check GET /me for the workspaces your credential actually reaches.

Handling errors well

def call(method: str, path: str, **kwargs) -> dict:
    response = http.request(method, path, **kwargs)

    if response.is_success:
        return response.json()

    problem = response.json()
    status = response.status_code
    kind = problem.get("type", "").rsplit("/", 1)[-1]

    # Transient. Pace off the header, not a fixed sleep.
    if status == 429:
        time.sleep(problem.get("retry_after_seconds")
                   or int(response.headers.get("Retry-After", "5")))
        return call(method, path, **kwargs)

    # Operational, not a contract change. Back off and try again later.
    # 502 is a failed dependency and is also worth retrying.
    if status == 502 or kind in ("api-disabled", "read-only-mode", "credit-balance-unavailable"):
        raise TemporarilyUnavailable(problem, retry_after=response.headers.get("Retry-After"))

    # Permanent until a human acts. Never retry these.
    # Status first: every *-not-found narrows 404, and 401 has five specific suffixes.
    if status in (401, 402) or kind in ("insufficient-scope", "insufficient-role"):
        raise NeedsHumanAttention(problem)

    # Your bug. Fix the request.
    raise ClientError(problem)

The three categories that matter:

1. Retry with backoff: rate-limited, api-disabled, read-only-mode.
2. Never retry, escalate to a human: invalid-credential, insufficient-scope, insufficient-role, quota-exhausted, workspace-not-writable.
3. Fix your request: invalid-request, conflict, method-not-allowed, not-found.

Getting help

Every response carries X-Request-Id, and every problem body repeats it as request_id. Quote it in any support conversation. It is what lets us find the exact request in the access log, and without it a report of "a call failed yesterday" is not actionable.