Add Troubleshooting section with additional context on API errors

[gunnaraasen]

While we have documentation available for the APIs exposed by Dedicated,

• the API contents are not exposed well in the docs search
• details of error responses and behavior does not have much context in the API docs

For a concrete example, we should provide advice on how clients should handle 429 and 503 responses.

Similar to the docs for our other products, the Cloud Dedicated docs should have a "Troubleshooting" section with a "FAQs" and/or "error messages" page with additional context on API (and other errors) which can be encountered. This could be similar to the Enterprise FAQs page.

Relevant URLs

• https://docs.influxdata.com/influxdb/cloud-dedicated/reference/api/

[jstirnaman]

@gunnaraasen We have troubleshooting pages specific to writing and querying--e.g. https://docs.influxdata.com/influxdb/cloud-dedicated/write-data/troubleshoot/#review-http-status-codes

The API spec doesn't specify 429 status code. I interpret your description to mean a customer is requesting a change for the API to return a 429?

Regarding "the API contents are not exposed well in the docs search", yeah our API docs implementation has some limitations. We're exploring better, more integrated options.

[jstirnaman]

Oh, sorry, the v1 /write spec does specify 429. I need to include that in Troubleshooting sections.

[jstirnaman]

Oh, sorry, the v1 /write spec does specify 429. I need to include that in Troubleshooting sections.

Nope, moving this to a new issue we can track: #5532

[jstirnaman]

Takeaways:

• details of error responses and behavior does not have much context in the API docs

• Link or copy Troubleshooting sections into the API ref docs.
• Remove API ref duplication (v1-compat vs v2 "legacy" - probably revert the inclusion of "legacy" endpoints in v2 docs)

• the API contents are not exposed well in the docs search

Reimplement the API ref docs to integrate them with the rest of the site.