Errors

The API uses conventional HTTP status codes and returns a consistent error object on every failure, so you can branch on error.code and surface error.message directly.

BASE URLhttps://<your-instance>/api/v1

The error object

Errors always come back under a top-level error key with a machine-readable code and a human-readable message. Schema validation failures add a details array carrying the underlying issues.

ERROR OBJECT

{
  "error": {
    "code": "bad_request",
    "message": "scope.paths must be an array of globs."
  }
}

Status codes

Every response carries one of these:

Code	Meaning
`400`	Malformed or invalid request — bad JSON, a failed schema check (`validation_error`, with `details`), or out-of-bounds input (`bad_request`).
`401`	Missing or invalid bearer token.
`403`	Authenticated, but not allowed — a maintainer-only action (repo settings, removal, coordination edits).
`404`	No such object — or the repo isn't visible to your token (access is deliberately masked as not-found).
`409`	Invalid status transition — e.g. reopening a merged log.
`502`	An upstream GitHub request failed.
`5xx`	Something broke on our side; safe to retry with backoff.

RESPONSE 400 Bad Request

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed",
    "details": [
      { "path": ["risk"], "message": "Invalid enum value" }
    ]
  }
}

Error codes

The error.code string is stable and safe to switch on. Archiving is idempotent — re-archiving an already-archived record returns 200 with the record, not a conflict.

ERROR CODES

# error.code values
validation_error     400 · body failed schema (see details)
bad_request          400 · malformed or out-of-bounds input
category_not_allowed 400 · notable category off for this repo
unauthorized         401 · missing / invalid token
forbidden            403 · not allowed (maintainer-only action)
not_found            404 · no such object, or repo not visible
invalid_transition   409 · illegal status change
upstream_error       502 · GitHub request failed
internal_error       500 · unexpected server error