Repository navigation
docs(influxdb3): note 5xx writes may be partially ingested - #7969
Open
reidkaufmann wants to merge 2 commits into
Open
reidkaufmann wants to merge 2 commits into
reidkaufmann wants to merge 2 commits into
Conversation
A 503 or 504 from a Dedicated or Clustered write can leave data ingested. Document this, recommend retrying with the same data, and add 504 to the retry guidance and API specs. Serverless gets the 503 note only.
reidkaufmann
requested review from
jstirnaman
and
a balanced review from Copilot
and removed request for
a team
October 30, 2026 18:16
Contributor
Vale Style Check Results
✅ Check passed |
github-actions
Bot
added
product:shared
Contributor
🔗 Link Check Results — Link Check Bot❌ 5 broken link(s) found — fix them before merging.
Broken Links
|
| Source File | URL | Issue |
|---|---|---|
content/influxdb3/cloud-dedicated/reference/internals/durability/_index.md |
https://support.influxdata.com/ | Network error: SSL certificate not trusted. Use --insecure if site is trusted (e… |
content/influxdb3/cloud-dedicated/write-data/troubleshoot/_index.md |
https://support.influxdata.com/ | Network error: SSL certificate not trusted. Use --insecure if site is trusted (e… |
content/influxdb3/cloud-serverless/write-data/troubleshoot/_index.md |
https://support.influxdata.com/ | Network error: SSL certificate not trusted. Use --insecure if site is trusted (e… |
content/influxdb3/clustered/reference/internals/durability/_index.md |
https://support.influxdata.com/ | Network error: SSL certificate not trusted. Use --insecure if site is trusted (e… |
content/influxdb3/clustered/write-data/troubleshoot/_index.md |
https://support.influxdata.com/ | Network error: SSL certificate not trusted. Use --insecure if site is trusted (e… |
Full details: workflow run summary and artifact. Last updated: 2026-10-30 20:08:28 UTC
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
Retry guidance omits explicit-timestamp safeguards for Serverless readers and API write endpoints, so following it after partial ingestion can create additional points.
2 open issues
What changed in this PR
This PR clarifies that InfluxDB 3 distributed writes can ingest some or all data despite returning a 5xx response, aligning troubleshooting guidance and API references.
Changes:
- Explains partial ingestion and insufficient ingester acknowledgments.
- Adds
504to retry guidance and examples, with timestamp and field-value precautions. - Updates Dedicated and Clustered write responses and adds partial-ingestion notes for Serverless.
| File | Description |
|---|---|
content/shared/v3-distributed-internals-reference/durability.md |
Explains retention and query visibility after insufficient acknowledgments. |
content/shared/influxdb3-write-guides/troubleshoot-distributed.md |
Clarifies error outcomes and expands retry guidance. |
api-docs/influxdb3/clustered/influxdb3-clustered-openapi.yaml |
Updates 503 and adds 504 descriptions for both write endpoints. |
api-docs/influxdb3/cloud-serverless/influxdb3-cloud-serverless-openapi.yaml |
Notes possible ingestion despite 503 responses. |
api-docs/influxdb3/cloud-dedicated/influxdb3-cloud-dedicated-openapi.yaml |
Updates 503 and adds 504 descriptions for both write endpoints. |
Review effort: Balanced
| Service unavailable. | ||
|
|
||
| - Returns this error if the server is temporarily unavailable to accept writes due to concurrent request limits or insufficient healthy ingesters. | ||
| - Some or all of the data may have been ingested. Retrying the write with the same data is safe and recommended. |
Contributor
Author
There was a problem hiding this comment.
Agreed. In 6948ad4 the 503 and 504 retry sentences in both the Dedicated and Clustered specs now read "If all points include explicit timestamps, retrying the write with the same data is safe and recommended."
| Writes are synchronous--the response status indicates the final status of the write and all ingested data is queryable. | ||
| Writes are synchronous. A `204` response means all data was ingested and is queryable. | ||
| A `5xx` response means the write didn't complete, but some or all of the data may have been ingested. | ||
| To make sure data is stored and consistent in query results, retry the write with the same data. |
Contributor
Author
There was a problem hiding this comment.
Agreed. In 6948ad4 the shared intro, which also renders for Serverless, now adds: "Include explicit timestamps; InfluxDB assigns the server time to points without one, so retrying them creates additional points."
Contributor
📦 PR Preview — Preview Bot
Changed pages (5)Preview auto-deploys on push. Will be cleaned up when PR closes. |
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
A
503or504from a Cloud Dedicated or Clustered write can leave some or all of the data ingested, but the docs say a non-204status is the final status of the write.This documents that
5xxwrites may be partially ingested and recommends retrying with the same data. It also adds504to the retry guidance and API specs. Serverless gets only the shared intro change and a one-line note on its503.Evidence
503when fewer ingesters than required acknowledge a write, including after one has stored it (rpc_write.rs).504is returned when the router stops waiting on an ingester. Once started, the ingester's write runs to completion even if the router disconnects (ingester/src/wal/wal_sink.rs).503for auth is returned when the router can't reach the authorization service (influxdb_iox#16371); invalid tokens get403.global-routerdeployments use write replication factor 2.Changes
troubleshoot-distributed.md:204vs5xx.503/504rows note possible ingestion, and their response body is listed as "JSON or plain text, depending on origin".504is added to the backoff guidance and examples.durability.md: what happens when fewer ingesters than required acknowledge a write.503note, plus new504responses for the v1 and v2 writes.503note only.