Improve Remote API documentation: `api/v1/prom/push`

[gotjosh]

Based on a conversation from #2383

At the moment, it is not clear what is the lifecycle of a WriteRequest when pushed to api/v1/prom/push:

• Which errors are reported; Assuming Return first validation error on sample ingestion #2383 is merged (got merged 😄), we only send back the first error we encounter when processing samples.
• How sample distribution/ingestion works; Samples are validated before distribution. The ones that do not pass validation are simply discarded, and the ones that do pass are processed. If a failure occurs on ingestion (e.g. duplicated timestamp+value) there are multiple scenarios to cover too.

Would we like to cover these?

[pracucci]

we only send back the first error we encounter when processing samples.

I would also explain the returned error is a 400, so that Prometheus does not resend the request but still Cortex signals back to Prometheus that some series have not been successfully ingested.

How sample distribution/ingestion works; Samples are validated before distribution

This is briefly explained in the architecture page (but not in details). We also reference some validation config options in arguments.md.

[stale]

This issue has been automatically marked as stale because it has not had any activity in the past 60 days. It will be closed in 15 days if no further activity occurs. Thank you for your contributions.

[pracucci]

Still valid