diff --git a/api-docs/cloud-serverless/ref.yml b/api-docs/cloud-serverless/ref.yml index e5e139d6b..bc8f18499 100644 --- a/api-docs/cloud-serverless/ref.yml +++ b/api-docs/cloud-serverless/ref.yml @@ -13839,18 +13839,16 @@ paths: Use this endpoint to send data in [line protocol](/influxdb/cloud-serverless/reference/syntax/line-protocol/) format to InfluxDB. - InfluxDB does the following when you send a write request: + InfluxDB Cloud Serverless does the following when you send a write request: - 1. Validates the request. - 2. If successful, attempts to [ingest data](/influxdb/cloud-serverless/reference/internals/durability/#data-ingest) from the request body; otherwise, responds with an [error status](/influxdb/cloud-serverless/write-data/troubleshoot/#review-http-status-codes). - 3. Ingests or rejects the entire batch and returns one of the following HTTP status codes: + 1. Validates the request. + 2. If successful, attempts to [ingest the data](/influxdb/cloud-serverless/reference/internals/durability/#data-ingest); [error](/influxdb/cloud-serverless/write-data/troubleshoot/#review-http-status-codes) otherwise. + 3. If some or all points in the batch are written, responds with an HTTP `204 "No Content"` status code, acknowledging that data is written and queryable; error otherwise. - - `204 No Content`: all data is ingested - - `400 Bad Request`: all data is rejected + - `204 "No Content"`: Data in the batch is written and queryable. + - `400 "Bad Request"`: The entire batch is rejected. - The response body contains error details about [rejected points](/influxdb/cloud-serverless/write-data/troubleshoot/#troubleshoot-rejected-points), up to 100 points. - - Writes are synchronous--the response status indicates the final status of the write and all ingested data is queryable. + If some points in the batch are rejected, the response body contains details about the [rejected points](/influxdb/cloud-serverless/write-data/troubleshoot/#troubleshoot-rejected-points). To ensure that InfluxDB handles writes in the order you request them, wait for the response before you send the next request. @@ -13864,13 +13862,14 @@ paths: #### Rate limits - `write` rate limits apply. + _Write_ rate limits apply. For more information, see [limits and adjustable quotas](/influxdb/cloud-serverless/admin/billing/limits/). #### Related guides + - [Get started writing data](/influxdb/cloud-serverless/get-started/write/) - [Write data with the InfluxDB API](/influxdb/cloud-serverless/get-started/write/) - - [Optimize writes to InfluxDB](/influxdb/cloud-serverless/write-data/best-practices/optimize-writes/) + - [Best practices for writing data](/influxdb/cloud-serverless/write-data/best-practices/) - [Troubleshoot issues writing data](/influxdb/cloud-serverless/write-data/troubleshoot/) operationId: PostWrite parameters: @@ -13993,23 +13992,45 @@ paths: responses: '204': description: | - Success. Data is written and queryable. - '400': + Success. + Data in the batch is written and queryable. + + If some points in the batch are rejected, the response body contains details about the [rejected points](/influxdb/cloud-serverless/write-data/troubleshoot/#troubleshoot-rejected-points), up to 100 points. content: application/json: examples: - measurementSchemaFieldTypeConflict: - summary: field type conflict thrown by an explicit bucket schema + partialWriteErrorWithRejectedPoints: + summary: Partial write rejects points with syntax errors value: code: invalid - message: 'failed to parse line protocol: error writing line 2: Unable to insert iox::column_type::field::integer type into column temp with type iox::column_type::field::string' + line: 2 + message: "failed to parse line protocol: + errors encountered on line(s): + error message for first rejected point + error message for second rejected point + error message for Nth rejected point (up to 100 rejected points)" + schema: + $ref: "#/components/schemas/LineProtocolError" + '400': + description: | + All data in the batch was rejected and not written. + + The response body contains details about the [rejected points](/influxdb/cloud-serverless/write-data/troubleshoot/#troubleshoot-rejected-points). + content: + application/json: + examples: + rejectedAllPoints: + summary: Rejected all points + value: + code: invalid + line: 2 + message: "failed to parse line protocol: + errors encountered on line(s): + error message for first rejected point + error message for second rejected point + error message for Nth rejected point (up to 100 rejected points)" schema: $ref: '#/components/schemas/LineProtocolError' - description: | - Bad request. The response body contains detail about the error. - - InfluxDB returns this error if the line protocol data in the request is malformed or contains a database schema conflict. - The response body contains the first malformed line in the data, and indicates what was expected. '401': $ref: '#/components/responses/AuthorizationError' '404': @@ -14043,9 +14064,7 @@ paths: The request payload is too large. InfluxDB rejected the batch and did not write any data. - #### InfluxDB Cloud: - - - Returns this error if the payload exceeds the 50MB size limit. + InfluxDB returns this error if the payload exceeds the 50MB size limit. '429': description: | Too many requests. @@ -14254,20 +14273,18 @@ paths: description: | Writes data to a bucket. - Use this endpoint for [InfluxDB v1 parameter compatibility](/influxdb/cloud-serverless/guides/api-compatibility/v1/) when sending data in [line protocol](/influxdb/cloud-serverless/reference/syntax/line-protocol/) format to InfluxDB. + Use this endpoint to send data in [line protocol](/influxdb/cloud-serverless/reference/syntax/line-protocol/) format to InfluxDB. InfluxDB Cloud Serverless does the following when you send a write request: - 1. Validates the request. - 2. If successful, attempts to [ingest data](/influxdb/cloud-serverless/reference/internals/durability/#data-ingest) from the request body; otherwise, responds with an [error status](/influxdb/cloud-serverless/write-data/troubleshoot/#review-http-status-codes). - 3. Ingests or rejects the entire batch and returns one of the following HTTP status codes: + 1. Validates the request. + 2. If successful, attempts to [ingest the data](/influxdb/cloud-serverless/reference/internals/durability/#data-ingest); [error](/influxdb/cloud-serverless/write-data/troubleshoot/#review-http-status-codes) otherwise. + 3. If some or all points in the batch are written, responds with an HTTP `204 "No Content"` status code, acknowledging that data is written and queryable; error otherwise. - - `204 No Content`: all data is ingested - - `400 Bad Request`: all data is rejected + - `204 "No Content"`: Data in the batch is written and queryable. + - `400 "Bad Request"`: The entire batch is rejected. - The response body contains error details about [rejected points](/influxdb/cloud-serverless/write-data/troubleshoot/#troubleshoot-rejected-points), up to 100 points. - - Writes are synchronous--the response status indicates the final status of the write and all ingested data is queryable. + If some points in the batch are rejected, the response body contains details about the [rejected points](/influxdb/cloud-serverless/write-data/troubleshoot/#troubleshoot-rejected-points). To ensure that InfluxDB handles writes in the order you request them, wait for the response before you send the next request. @@ -14317,7 +14334,7 @@ paths: name: precision schema: type: string - - description: When present, its value indicates to the database that compression is applied to the line protocol body. + - description: When present, indicates that compression is applied to the line protocol body. in: header name: Content-Encoding schema: @@ -14335,14 +14352,47 @@ paths: description: Line protocol body required: true responses: - '204': - description: Success. Data is ingested and queryable. - '400': + "204": + description: | + Success. + Data in the batch is written and queryable. + + If some points in the batch are rejected, the response body contains details about the [rejected points](/influxdb/cloud-serverless/write-data/troubleshoot/#troubleshoot-rejected-points), up to 100 points. content: application/json: + examples: + partialWriteErrorWithRejectedPoints: + summary: Partial write rejects points with syntax errors + value: + code: invalid + line: 2 + message: "failed to parse line protocol: + errors encountered on line(s): + error message for first rejected point + error message for second rejected point + error message for Nth rejected point (up to 100 rejected points)" + schema: + $ref: "#/components/schemas/LineProtocolError" + '400': + description: | + All data in the batch is rejected and not written. + + The response body contains details about the [rejected points](/influxdb/cloud-serverless/write-data/troubleshoot/#troubleshoot-rejected-points). + content: + application/json: + examples: + rejectsAllPoints: + summary: Rejected all points + value: + code: invalid + line: 2 + message: "failed to parse line protocol: + errors encountered on line(s): + error message for first rejected point + error message for second rejected point + error message for Nth rejected point (up to 100 rejected points)" schema: $ref: '#/components/schemas/LineProtocolError' - description: Line protocol poorly formed and no points were written. Response can be used to determine the first malformed line in the body line-protocol. All data in body was rejected and not written. '401': content: application/json: @@ -14385,6 +14435,7 @@ paths: description: Internal server error summary: Write data using the InfluxDB v1 API tags: + - Data I/O endpoints - Write security: - TokenAuthentication: [] @@ -14523,7 +14574,7 @@ tags: |:------------------------ |:--------------------- |:-------------------------------------------| | `Accept` | string | The content type that the client can understand. | | `Authorization` | string | The authorization scheme and credential. | - | `Content-Length` | integer | The size of the entity-body, in bytes, sent to the database. | + | `Content-Length` | integer | The size of the entity-body, in bytes. | | `Content-Type` | string | The format of the data in the request body. | name: Headers x-traitTag: true @@ -14629,8 +14680,9 @@ tags: |  Code  | Status | Description | |:-----------:|:------------------------ |:--------------------- | | `200` | Success | | - | `204` | No content | The request is successful and no data is returned. For example, The [`/write` and `/api/v2/write` endpoints](#tag/Write) return this status code if all data in the batch is written and queryable. | - | `400` | Bad request | InfluxDB can't parse the request due to an incorrect parameter or bad syntax. For _writes_, the error may indicate one of the following problems: | + | `201` | Created | Successfully created a resource. The response body may contain details. | + | `204` | No content | The request succeeded. InfluxDB doesn't typically return a response body for the operation. The [`/write`](#operation/PostLegacyWrite) and [`/api/v2/write`](#operation/PostWrite) endpoints return a response body if some points are written and some are rejected. | + | `400` | Bad request | InfluxDB can't parse the request due to an incorrect parameter or bad syntax. For _writes_, the error may indicate one of the following problems: | | `401` | Unauthorized | May indicate one of the following: | | `404` | Not found | Requested resource was not found. `message` in the response body provides details about the requested resource. | | `405` | Method not allowed | The API path doesn't support the HTTP method used in the request--for example, you send a `POST` request to an endpoint that only allows `GET`. | diff --git a/content/influxdb/cloud-serverless/admin/buckets/manage-explicit-bucket-schemas.md b/content/influxdb/cloud-serverless/admin/buckets/manage-explicit-bucket-schemas.md index 2889deb5e..84e0a0eb4 100644 --- a/content/influxdb/cloud-serverless/admin/buckets/manage-explicit-bucket-schemas.md +++ b/content/influxdb/cloud-serverless/admin/buckets/manage-explicit-bucket-schemas.md @@ -19,7 +19,7 @@ alt_links: {{% warn %}} #### Don't use explicit schemas with InfluxDB v3 -We don't recommend using **explicit bucket schemas** with InfluxDB v3. +Don't use **explicit bucket schemas** with InfluxDB v3. The sections on this page provide help for managing and troubleshooting `explicit` buckets you may already have. {{% /warn %}} diff --git a/content/influxdb/cloud-serverless/write-data/troubleshoot.md b/content/influxdb/cloud-serverless/write-data/troubleshoot.md index 1ab05fc7a..64a67b731 100644 --- a/content/influxdb/cloud-serverless/write-data/troubleshoot.md +++ b/content/influxdb/cloud-serverless/write-data/troubleshoot.md @@ -3,7 +3,9 @@ title: Troubleshoot issues writing data seotitle: Troubleshoot issues writing data to InfluxDB weight: 106 description: > - Troubleshoot issues writing data. Find response codes for failed writes. Discover how writes fail, from exceeding rate or payload limits, to syntax errors and schema conflicts. + Troubleshoot issues writing data. + Find response codes for failed writes. + Discover how writes fail, from exceeding rate or payload limits, to syntax errors and schema conflicts. menu: influxdb_cloud_serverless: name: Troubleshoot issues @@ -17,15 +19,12 @@ related: Learn how to avoid unexpected results and recover from errors when writing to {{% product-name %}}. - - [Handle write responses](#handle-write-responses) - [Review HTTP status codes](#review-http-status-codes) - [Troubleshoot failures](#troubleshoot-failures) - [Troubleshoot rejected points](#troubleshoot-rejected-points) - - ## Handle write responses {{% product-name %}} does the following when you send a write request: @@ -34,10 +33,10 @@ Learn how to avoid unexpected results and recover from errors when writing to {{ 2. If successful, attempts to [ingest data](/influxdb/cloud-serverless/reference/internals/durability/#data-ingest) from the request body; otherwise, responds with an [error status](#review-http-status-codes). 3. Ingests or rejects the entire batch and returns one of the following HTTP status codes: - - `204 No Content`: all data is ingested + - `204 No Content`: data is ingested and queryable - `400 Bad Request`: all data is rejected - The response body contains error details about [rejected points](#troubleshoot-rejected-points), up to 100 points. + If points are rejected, the `204` or `400` response body contains error details about [rejected points](#troubleshoot-rejected-points), up to 100 points. Writes are synchronous--the response status indicates the final status of the write and all ingested data is queryable. @@ -50,17 +49,17 @@ InfluxDB uses conventional HTTP status codes to indicate the success or failure The `message` property of the response body may contain additional details about the error. {{< product-name >}} returns one the following HTTP status codes for a write request: -| HTTP response code | Message | Description | -| :-------------------------------| :-----------------------------------------------------------------------| :------------- | -| `204 "Success"` | | If InfluxDB ingested the data | -| `400 "Bad request"` | `message` contains the first malformed line | If request data is malformed | +| HTTP response code | Response body | Description | +| :-------------------------------| :--------------------------------------------------------------- | :------------- | +| `204 "No Content"` | error details about rejected points, up to 100 points: `line` contains the first rejected line, `message` describes rejected points | If InfluxDB ingested some or all of the data | +| `400 "Bad request"` | `line` contains the first malformed line, `message` describes rejected points | If request data is malformed | | `401 "Unauthorized"` | | If the `Authorization` header is missing or malformed or if the [token](/influxdb/cloud-serverless/admin/tokens/) doesn't have [permission](/influxdb/cloud-serverless/admin/tokens/create-token/) to write to the bucket. See [examples using credentials](/influxdb/cloud-serverless/get-started/write/#write-line-protocol-to-influxdb) in write requests. | | `403 "Forbidden"` | `message` contains details about the error | If the data isn't allowed (for example, falls outside of the bucket's retention period). | `404 "Not found"` | requested **resource type** (for example, "organization" or "bucket"), and **resource name** | If a requested resource (for example, organization or bucket) wasn't found | | `413 “Request too large”` | cannot read data: points in batch is too large | If a request exceeds the maximum [global limit](/influxdb/cloud-serverless/admin/billing/limits/) | -| `429 “Too many requests”` | `Retry-After` header: xxx (seconds to wait before retrying the request) | If a request exceeds your plan's [adjustable service quotas](/influxdb/cloud-serverless/admin/billing/limits/#adjustable-service-quotas) | +| `429 “Too many requests”` | | If the number of requests exceeds the [adjustable service quota](/influxdb/cloud-serverless/admin/billing/limits/#adjustable-service-quotas). The `Retry-After` header contains the number of seconds to wait before trying the write again. | If a request exceeds your plan's [adjustable service quotas](/influxdb/cloud-serverless/admin/billing/limits/#adjustable-service-quotas) | `500 "Internal server error"` | | Default status for an error | -| `503` `"Service unavailable"` | | If the server is temporarily unavailable to accept writes. The `Retry-After` header describes when to try the write again. +| `503 "Service unavailable"` | | If the server is temporarily unavailable to accept writes. The `Retry-After` header contains the number of seconds to wait before trying the write again. The `message` property of the response body may contain additional details about the error. If your data did not write to the bucket, see how to [troubleshoot rejected points](#troubleshoot-rejected-points). @@ -111,4 +110,4 @@ The following example shows a response body for a write request that contains tw } ``` -Check for [field data type](/influxdb/cloud-serverless/reference/syntax/line-protocol/#data-types-and-format) differences between the rejected data point and points in the bucket that have the same measurement and day--for example, did you attempt to write `string` data to an `int` field? +Check for [field data type](/influxdb/cloud-serverless/reference/syntax/line-protocol/#data-types-and-format) differences between the rejected data point and points within the same database and partition--for example, did you attempt to write `string` data to an `int` field?