Deployed 5086daf with MkDocs version: 1.6.1

dev/rest-api/dashboard/index.html

@@ -2250,7 +2250,7 @@ dashboard UI that wants history must keep its own copy.</p>
 <div class="language-text highlight"><pre><span></span><code><span id="__span-1-1"><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a>unshackle serve --remote-only --quiet
 </span></code></pre></div>
 <h2 id="endpoints">Endpoints<a class="headerlink" href="#endpoints" title="Permanent link">&para;</a></h2>
-<p>All are <code>GET</code>.</p>
+<p>All are <code>GET</code>, except the two <code>drain</code> routes.</p>
 <table>
 <thead>
 <tr>
@@ -2261,7 +2261,15 @@ dashboard UI that wants history must keep its own copy.</p>
 <tbody>
 <tr>
 <td><code>/api/dashboard/status</code></td>
-<td>Version, <code>code_hash</code>, bind host and port, <code>mode</code> (<code>full</code>, <code>api_only</code>, <code>remote_only</code>), uptime, <code>requests_total</code>, <code>requests_rejected</code> (401s), <code>requests_by_key</code> (label → count), <code>errors</code> (error counts by service tag, then by <code>error_code</code>), configured service count (the same services as <code>/api/dashboard/services</code>), session count, <code>max_sessions</code> (<code>null</code> when the operator configured no limit), <code>session_ttl</code>, job counts by status. The service count includes services that failed to import - use <code>/api/dashboard/services</code> for the number that loaded.</td>
+<td>Version, <code>code_hash</code>, bind host and port, <code>mode</code> (<code>full</code>, <code>api_only</code>, <code>remote_only</code>), uptime, <code>requests_total</code>, <code>requests_rejected</code> (401s), <code>requests_by_key</code> (label → count), <code>errors</code> (error counts by service tag, then by <code>error_code</code>), configured service count (the same services as <code>/api/dashboard/services</code>), session count, <code>max_sessions</code> (<code>null</code> when the operator configured no limit), <code>session_ttl</code>, job counts by status. <code>draining</code> is <code>true</code> while a drain is on. The service count includes services that failed to import - use <code>/api/dashboard/services</code> for the number that loaded.</td>
+</tr>
+<tr>
+<td><code>POST /api/dashboard/drain</code></td>
+<td>Starts a drain before a restart and returns the <code>/status</code> body. The server then refuses each new remote session, download job and job retry with <code>SERVER_DRAINING</code> (409). Open remote sessions and jobs continue, and each open remote session gets a warning in its service log, which the client shows to the user. Poll <code>/status</code> until <code>sessions</code> and the queued and downloading jobs are 0, then restart. The drain ends when the process stops. A second call changes nothing.</td>
+</tr>
+<tr>
+<td><code>DELETE /api/dashboard/drain</code></td>
+<td>Cancels the drain and returns the <code>/status</code> body. The server accepts new work again.</td>
 </tr>
 <tr>
 <td><code>/api/dashboard/sessions</code></td>

dev/rest-api/endpoints/index.html

@@ -3268,7 +3268,7 @@
 <td>Service list returned.</td>
 </tr>
 <tr>
-<td><code>500</code></td>
+<td><code>422</code></td>
 <td>Unexpected server error (<code>INTERNAL_ERROR</code>).</td>
 </tr>
 </tbody>
@@ -3602,7 +3602,7 @@ ignore it safely. See <a href="../../creating-a-service/#split-episodes">Split e
 <td>Title not found.</td>
 </tr>
 <tr>
-<td><code>500</code></td>
+<td><code>422</code></td>
 <td><code>INTERNAL_ERROR</code></td>
 <td>Unexpected error.</td>
 </tr>
@@ -5429,7 +5429,7 @@ A slow answer arrives as a <a href="#slow-responses">slow response</a>.</p>
 </div>
 <h3 id="error-codes-and-default-status">Error codes and default status<a class="headerlink" href="#error-codes-and-default-status" title="Permanent link">&para;</a></h3>
 <p>The <a href="../errors/#error-code-catalogue">error code catalogue</a> gives the default HTTP status of each error code.</p>
-<p>When a generic (uncategorized) exception reaches a handler, unshackle inspects its message and type to pick a code. For example, messages mentioning "connection" or "timeout" become <code>NETWORK_ERROR</code> (503, retryable), "rate limit" or "429" become <code>RATE_LIMITED</code> (429, retryable), and anything unrecognized collapses to <code>INTERNAL_ERROR</code> (500).</p>
+<p>When a generic (uncategorized) exception reaches a handler, unshackle inspects its message and type to pick a code. For example, messages mentioning "connection" or "timeout" become <code>NETWORK_ERROR</code> (424, retryable), "rate limit" or "429" become <code>RATE_LIMITED</code> (429, retryable), and anything unrecognized collapses to <code>INTERNAL_ERROR</code> (422).</p>
 <hr />
 <h2 id="see-also">See also<a class="headerlink" href="#see-also" title="Permanent link">&para;</a></h2>
 <ul>

dev/rest-api/errors/index.html

@@ -1782,10 +1782,10 @@
 </li>
         
           <li class="md-nav__item">
-  <a href="#server-errors-5xx" class="md-nav__link">
+  <a href="#server-errors-422-and-424" class="md-nav__link">
     <span class="md-ellipsis">
       
-        Server errors (5xx)
+        Server errors (422 and 424)
       
     </span>
   </a>
@@ -2198,10 +2198,10 @@
 </li>
         
           <li class="md-nav__item">
-  <a href="#server-errors-5xx" class="md-nav__link">
+  <a href="#server-errors-422-and-424" class="md-nav__link">
     <span class="md-ellipsis">
       
-        Server errors (5xx)
+        Server errors (422 and 424)
       
     </span>
   </a>
@@ -2436,12 +2436,13 @@ When it is absent, assume the request will keep failing until you change somethi
 <h2 id="error-code-catalogue">Error code catalogue<a class="headerlink" href="#error-code-catalogue" title="Permanent link">&para;</a></h2>
 <p>Every code below is a member of the <code>APIErrorCode</code> enumeration. The <strong>Status</strong> column
 is the default HTTP status the server returns for that code. A handler can override
-the status in special cases (for example, a network error is always forced to <code>503</code>),
-but the defaults hold for the overwhelming majority of responses.</p>
+the status in special cases, but the defaults hold for the overwhelming majority of responses.</p>
+<p>The server never answers with a <code>5xx</code> status. A proxy such as Cloudflare can replace the
+body of a <code>5xx</code> with its own page, and the JSON error is then lost. Server-side failures
+use <code>422</code>, and the ones that a retry can fix use <code>424</code>. Read <code>error_code</code> to tell them apart.
+A <code>5xx</code> that a client receives comes from a proxy in front of the server, for example
+while the server restarts.</p>
 <h3 id="client-errors-4xx">Client errors (4xx)<a class="headerlink" href="#client-errors-4xx" title="Permanent link">&para;</a></h3>
-<p><code>SERVICE_ERROR</code> and <code>DRM_ERROR</code> are upstream failures, but they use <code>422</code>, not <code>502</code>.
-A proxy such as Cloudflare replaces the body of a <code>502</code> or <code>504</code> with its own page, and
-the JSON error is then lost.</p>
 <table>
 <thead>
 <tr>
@@ -2522,6 +2523,11 @@ the JSON error is then lost.</p>
 <td>The target resource is in a state that disallows the action (retrying a running job, prioritising a non-queued job, clearing cache during an active download).</td>
 </tr>
 <tr>
+<td><code>SERVER_DRAINING</code></td>
+<td>409</td>
+<td>The server is about to restart and starts no new remote session or download job. Open work continues. Retryable after the restart.</td>
+</tr>
+<tr>
 <td><code>SERVICE_ERROR</code></td>
 <td>422</td>
 <td>The streaming service's API returned an error, or the service does not support the requested operation.</td>
@@ -2548,7 +2554,7 @@ header. Read <code>Retry-After</code> and wait it out rather than retrying on a
 the window is fixed, so an early retry only spends the next window. See
 <a href="../authentication/#rate-limit-rejections">Authentication</a>.</p>
 </div>
-<h3 id="server-errors-5xx">Server errors (5xx)<a class="headerlink" href="#server-errors-5xx" title="Permanent link">&para;</a></h3>
+<h3 id="server-errors-422-and-424">Server errors (422 and 424)<a class="headerlink" href="#server-errors-422-and-424" title="Permanent link">&para;</a></h3>
 <table>
 <thead>
 <tr>
@@ -2560,27 +2566,27 @@ the window is fixed, so an early retry only spends the next window. See
 <tbody>
 <tr>
 <td><code>INTERNAL_ERROR</code></td>
-<td>500</td>
-<td>An unexpected server-side error. This is the fallback for any exception the server could not categorise.</td>
+<td>422</td>
+<td>An unexpected server-side error. This is the fallback for any exception the server could not categorise, and for an exception that no handler caught.</td>
 </tr>
 <tr>
 <td><code>DOWNLOAD_ERROR</code></td>
-<td>500</td>
+<td>422</td>
 <td>The download process itself failed.</td>
 </tr>
 <tr>
 <td><code>WORKER_ERROR</code></td>
-<td>500</td>
+<td>422</td>
 <td>The download worker subprocess errored out.</td>
 </tr>
 <tr>
 <td><code>NETWORK_ERROR</code></td>
-<td>503</td>
+<td>424</td>
 <td>A network connectivity problem (connection, timeout, DNS, TLS). Retryable.</td>
 </tr>
 <tr>
 <td><code>SERVICE_UNAVAILABLE</code></td>
-<td>503</td>
+<td>424</td>
 <td>The service is temporarily unavailable or under maintenance. Retryable.</td>
 </tr>
 </tbody>
@@ -2588,7 +2594,8 @@ the window is fixed, so an early retry only spends the next window. See
 <div class="admonition note">
 <p class="admonition-title">Fallback status</p>
 <p>If a code is ever emitted without a mapped status, the server falls back to
-<code>500</code>. In practice every code above has an explicit mapping.</p>
+<code>422</code>. In practice every code above has an explicit mapping. A middleware
+in every server mode also changes any <code>5xx</code> answer, such as one from a CDM subapplication, to <code>422</code>.</p>
 </div>
 <h2 id="how-the-server-produces-errors">How the server produces errors<a class="headerlink" href="#how-the-server-produces-errors" title="Permanent link">&para;</a></h2>
 <p>Understanding where an error comes from helps interpret it.</p>
@@ -2616,7 +2623,7 @@ The classification is keyword-based, checked in order:</p>
 </tr>
 <tr>
 <td><code>connection</code>, <code>timeout</code>, <code>network</code>, <code>unreachable</code>, <code>socket</code>, <code>dns</code>, <code>resolve</code> (or <code>ConnectionError</code>, <code>TimeoutError</code>, <code>URLError</code>, <code>SSLError</code>)</td>
-<td><code>NETWORK_ERROR</code> (503)</td>
+<td><code>NETWORK_ERROR</code> (424)</td>
 <td>yes</td>
 </tr>
 <tr>
@@ -2641,7 +2648,7 @@ The classification is keyword-based, checked in order:</p>
 </tr>
 <tr>
 <td><code>service unavailable</code>, <code>503</code>, <code>maintenance</code>, <code>temporarily unavailable</code></td>
-<td><code>SERVICE_UNAVAILABLE</code> (503)</td>
+<td><code>SERVICE_UNAVAILABLE</code> (424)</td>
 <td>yes</td>
 </tr>
 <tr>
@@ -2651,7 +2658,7 @@ The classification is keyword-based, checked in order:</p>
 </tr>
 <tr>
 <td>anything else</td>
-<td><code>INTERNAL_ERROR</code> (500)</td>
+<td><code>INTERNAL_ERROR</code> (422)</td>
 <td>no</td>
 </tr>
 </tbody>

dev/rest-api/quickstart/index.html

@@ -2781,12 +2781,12 @@
 </tr>
 <tr>
 <td><code>INTERNAL_ERROR</code></td>
-<td>500</td>
+<td>422</td>
 <td>Unexpected server-side failure</td>
 </tr>
 <tr>
 <td><code>NETWORK_ERROR</code></td>
-<td>503</td>
+<td>424</td>
 <td>Connection/timeout reaching the service (retryable)</td>
 </tr>
 </tbody>