Add reference for Janus errors

divviup · Dec 22, 2023 · 46b8061 · 46b8061
1 parent 44bb3df
commit 46b8061
Show file tree

Hide file tree

Showing 3 changed files with 56 additions and 5 deletions.
diff --git a/docs/glossary.md → docs/references/glossary.md b/docs/glossary.md → docs/references/glossary.md
@@ -1,9 +1,7 @@
 ---
-# Glossary position should be second to last. The resources category is always
-# last, because we've manually specified it last in the array in sidebars.js.
-# The sidebar_position in this file doesn't override the one in sidebars.js, so
-# we can just set it to an arbitrarily high value.
-sidebar_position: 999
+# This page was originally on /glossary, so keep it there to avoid breaking user
+# links.
+slug: /glossary
 ---
 
 # Glossary

diff --git a/docs/references/janus-errors.md b/docs/references/janus-errors.md
@@ -0,0 +1,40 @@
+# Janus Errors
+
+This reference provides a list of errors that you might encounter when
+interacting with a Janus aggregator.
+
+## DAP Errors
+
+Most errors that Janus return are defined in DAP. A DAP error looks something
+like this:
+
+```json
+{
+  "type": "urn:ietf:params:ppm:dap:error:missingTaskID",
+  "title": "HPKE configuration was requested without specifying a task ID.",
+  "status": 400
+}
+```
+
+The `type` field defines a URN that is defined in the [DAP specification][1].
+
+[1]: https://www.ietf.org/archive/id/draft-ietf-ppm-dap-07.html#name-errors
+
+## Non-DAP Errors
+
+Some errors that Janus encounter are not defined in DAP. A list of these errors
+and troubleshooting techniques follows.
+
+### Collection Job Abandoned
+
+A Janus leader aggregator returns this error when it abandons a collection job.
+The leader has stopped processing the job. The job can no longer be collected,
+and any polling attempts should stop.
+
+This can happen if the paired helper aggregator cannot be contacted. If you are
+self-hosting a helper aggregator for the collection job's task, check that it is
+working correctly and reachable.
+
+Rarely, this error indicates a bug in Janus.
+
+You should contact the Janus operators for assistance.
diff --git a/docs/references/references.md b/docs/references/references.md
@@ -0,0 +1,13 @@
+---
+# References position should be second to last. The resources category is always
+# last, because we've manually specified it last in the array in sidebars.js.
+# The sidebar_position in this file doesn't override the one in sidebars.js, so
+# we can just set it to an arbitrarily high value.
+sidebar_position: 999
+---
+
+import DocCardList from "@theme/DocCardList";
+
+# References
+
+<DocCardList />