BCDA-7867: Add 429 recommendations

_includes/build/best_practices.html

@@ -0,0 +1,7 @@
+<div>
+    <p>
+        There are many ways to accomplish the same objective within BCDA, and following our list of best practices can ensure optimal performance for all consumers of BCDA. 
+    </p>
+
+</div>
+

_includes/build/best_practices_429.html

@@ -0,0 +1,15 @@
+
+<div>
+    <p>Occasionally, when interacting with BCDA, you might encounter responses with a status code of <code>429 Too Many Requests</code>.</p>
+
+    <p>BCDA assigns 429 response codes based on two independent criteria:</p>
+
+    <ol>
+      <li>Making too many HTTP requests in a period of time.</li>
+      <li>Attempting to create duplicate jobs.</li>
+    </ol>
+
+    <p>Regardless of the reason, BCDA will include a <strong>Retry-After</strong> header in its response. It's considered best practice to wait until the period specified in this header has elapsed before making further requests. This ensures your client can adapt without manual intervention, even if the rate-limiting parameters change.</p>
+
+    <p>Concerning duplicate jobs, BCDA defines them as attempts to recreate a job already marked as "In-Progress". For reference, you can view both existing and past jobs by accessing the job history endpoint at <code>/jobs</code>.</p>
+</div>

_includes/build/requesting_data_runouts.html

@@ -61,9 +61,10 @@ <h4>Start a Job using 'runout' with /Group Explanation</h4>
 	<p>
 		If the request was successful, a 202 Accepted response code will be returned and the response will include a Content-Location header. The value of the Content-Location header indicates the location to check for job status and outcome. In the example header above, the number 42 in the URL represents the ID of the export job. The claims returned in the job will be filtered to have a serviceDate of 12/31/2020 or before.
 	</p>
-	<p>
-		If you're already requesting data from one endpoint and try to request data from that endpoint again while the first request is processing, you'll receive a 429 Too Many Requests error.
-	</p>
+	<p> 
+		If you're already requesting data from one endpoint and try to request data from that endpoint again while the first request is processing, you'll receive a 429 Too Many Requests error. For guidance on how to handle 429 errors, refer to our <a href="#handling-429-error">best practices</a>.
+	</p> 
+
 
 <h3>Step 3: Check the job status</h3>
 	<p>See <a href="#checkJob" class="in-text__link"><em>Step 3: Check the job status</em></a> in the Request Data section above.</p>

build.html

@@ -116,6 +116,20 @@
             </li>
           </ul> 
         </li>
+
+
+        <li class="ds-c-vertical-nav__item">
+          <a class="ds-c-vertical-nav__label ds-c-vertical-nav__label" href="#bulk-best-practices">
+            Best Practices
+          </a>
+          <ul class="ds-c-vertical-nav__subnav">
+            <li class="ds-c-vertical-nav__subnav">
+              <a class="ds-c-vertical-nav__label ds-c-vertical-nav__label" href="#handling-429-error">
+                Handling 429 status codes
+              </a>
+            </li>
+          </ul>
+        </li>
       </ul>
     </aside>
     <!-- Table of Contents END -->
@@ -266,6 +280,23 @@ <h2>
           </div>
         </div>        
       </div>
+
+      <div id="bulk-best-practices" class="guide-content">
+        <h1>
+          Best Practices for Utilizing BCDA
+        </h1>
+        <div class="ds-u-font-size--base ">
+          {% include build/best_practices.html %}
+        </div>
+        <div id="handling-429-error">
+          <h2>
+            Handling 429 status codes
+          </h2>
+          <div class="ds-u-font-size--base">
+            {% include build/best_practices_429.html %}
+          </div>
+        </div>
+      </div>
     </main>
   </div>
 </div>