Improve upload and download API docs (#2955)

* Improve upload and download API docs

This improves the HTTP status codes, adds response headers where
applicable, and adds a first-pass section on improving symbol upload
success rates.

This should help users who are using the download and upload APIs know
what to do in certain status code situations that were previously
undocumented.

This specifies the response headers so we can write systemtests for
them.

This will help people writing symbol upload jobs with a set of things
they can look at to improve the likelihood those jobs finish
successfully. We can hone this section over time.

* Address PR comments

This fixes the location redirect download API docs by moving the
separate request into a new section. This adds status code items for
502, 503, and 504 where missing.

* Clarify situations where tips would be helpful

docs/download.rst

@@ -106,9 +106,12 @@ Downloading API
 
    :statuscode 200: symbol file exists
    :statuscode 404: symbol file does not exist
+   :statuscode 429: your request has been rate-limited; sleep for a bit and retry
    :statuscode 500: sleep for a bit and retry; if retrying doesn't work, then please
        file a bug report
+   :statuscode 502: sleep for a bit and retry
    :statuscode 503: sleep for a bit and retry
+   :statuscode 504: sleep for a bit and retry
 
 
 .. http:get:: /(str:debug_filename)/(hex:debug_id)/(str:symbol_file)
@@ -173,15 +176,18 @@ Downloading API
 
    :query _refresh: use ``_refresh=1`` to force Tecken to update cache
 
+   :resheader Location: redirect location for the file; see :http:get:`SYMBOLFILE`.
+
    :statuscode 302: symbol file was found--follow redirect url in ``Location`` header in
        the response to get to the final url
-   :statuscode 400: requested symbol file has bad characters
+   :statuscode 400: param values have bad characters in them or are otherwise invalid
    :statuscode 404: symbol file was not found
-   :statuscode 429: sleep for a bit and retry
-   :statuscode 500: sleep for a bit and retry; if retrying doesn't work, then please
-       file a bug report
-   :statuscode 503: sleep for a bit and retry; if retrying doesn't work, then please
-       file a bug report
+   :statuscode 429: your request has been rate-limited; sleep for a bit and retry
+   :statuscode 500: there's an error with the server; sleep for a bit and
+       retry; if retrying doesn't work, then please file a bug report
+   :statuscode 502: sleep for a bit and retry
+   :statuscode 503: sleep for a bit and retry
+   :statuscode 504: sleep for a bit and retry
 
 
 .. http:get:: /(str:code_filename)/(hex:code_id)/(str:symbol_file)
@@ -257,3 +263,26 @@ Downloading API
    :param hex code_id: the code id in hex characters all upper-cased
 
    :param str symbol_file: the filename of the symbol file; ends with ``.sym``
+
+
+.. http:get:: SYMBOLFILE
+
+   This covers the download API response ``Location`` value url redirect.
+
+   :reqheader User-Agent: please provide a unique user agent to make it easier for us
+       to help you debug problems
+
+   :resheader Content-Length: length of the response body; if the body is
+       compressed, it's the size of the compressed body
+   :resheader Content-Type: content type of the response after decompressing
+       it; will be text/plain for symbol files
+   :resheader Content-Encoding: (optional) set to ``gzip`` if the object is
+       gzip-compressed; note that ``.sym`` files are compressed even though the
+       file extension doesn't indicate that
+
+   :statuscode 404: symbol file was not found
+   :statuscode 500: there's an error with the server; sleep for a bit and
+       retry; if retrying doesn't work, then please file a bug report
+   :statuscode 502: sleep for a bit and retry
+   :statuscode 503: sleep for a bit and retry
+   :statuscode 504: sleep for a bit and retry

docs/upload.rst

@@ -303,6 +303,22 @@ The auth token is sent as an ``Auth-Token`` HTTP header in the HTTP POST.
    created on stage won't work in production.
 
 
+Improving symbol upload success rate
+====================================
+
+Tecken tries to do as much as it can when handling the symbol upload request.
+Subsequent attempts will pick up where they left off--files that have been
+processed won't be reprocessed.
+
+If you find your symbols upload job is getting HTTP 429 or 5xx responses often
+or it doesn't seem like symbol uploads are being completed, try these tips:
+
+1. break up the zip file into smaller zip files to upload
+2. increase the amount of time you're giving to uploading symbols, increase the
+   number of retry attempts, and increase the time between retry attempts
+3. change the time of day that you're doing symbol uploads
+
+
 Upload: /upload/
 ================
 
@@ -342,16 +358,13 @@ Upload: /upload/
    :statuscode 403: your auth token is invalid and you need to get a new one
    :statuscode 413: your upload is too large; split it into smaller files or switch to
        upload by download url
-   :statuscode 429: wait and retry
-   :statuscode 500: wait and retry; if retrying continues to fail, then please
-       file a bug report
-   :statuscode 503: wait and retry
-
-
-.. Note::
-
-   For retrying, we suggest waiting 15 seconds between retry attempts. This
-   gives the service time to scale up and recover from ephemeral issues.
+   :statuscode 429: your request has been rate-limited; sleep for a bit and retry
+   :statuscode 500: there's an error with the server; sleep for a bit and
+       retry; if retrying doesn't work, then please file a bug report
+   :statuscode 502: sleep for a bit and retry
+   :statuscode 503: sleep for a bit and retry
+   :statuscode 504: the request is taking too long to complete; sleep for a bit
+       and retry
 
 
 Symbols processing