Errors

Errors use one envelope:

{
  "error": {
    "code": "FORBIDDEN",
    "message": "This key lacks the required scope: events.read"
  }
}

Match on code, not on message — the wording may be improved at any time, the codes will not change without a version bump.

Codes

Status	Code	What happened
400	`BAD_REQUEST`	A query parameter was malformed — most often an `updatedSince` that is not an ISO 8601 date.
401	`UNAUTHENTICATED`	No key, a malformed key, a revoked key, an expired key, or a reserved `nvx_test_` key.
402	`UPGRADE_REQUIRED`	The workspace plan does not include API access. Spectrum and above.
403	`FORBIDDEN`	The key is valid but lacks the scope this endpoint requires.
404	`NOT_FOUND`	No such record in your workspace.
429	`RATE_LIMITED`	Too many requests. Honour `Retry-After`.
500	`INTERNAL_ERROR`	Something broke on our side. Safe to retry with backoff.

A note on 404

A 404 means the record does not exist for your workspace. An id belonging to another workspace is indistinguishable from one that never existed — that is deliberate, and it is why guessing ids reveals nothing.

Distinguishing 401 from 403

401 — we could not accept your key at all.
403 — your key is fine, but it does not carry the scope this endpoint needs. Add the scope in Settings → API, or use a key that has it.

Versioning Events