{"record":{"id":"8064a320a26be429","repo":"influxdata/influxdb","slug":"error-code","errorCode":"{error_code}","errorMessage":"server responded with error [{code}]: {message}","messagePattern":"server responded with error \\[(.+?)\\]: (.+?)","errorType":"http","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"influxdb3_client/src/lib.rs","lineNumber":56,"sourceCode":"        \"provided parameter ('{name}') could not be converted \\\n        to a statment parameter\"\n    )]\n    ConvertQueryParam {\n        name: String,\n        #[source]\n        source: iox_query_params::Error,\n    },\n\n    #[error(\"invalid UTF8 in response: {0}\")]\n    InvalidUtf8(#[from] FromUtf8Error),\n\n    #[error(\"failed to parse JSON response: {}\", reqwest_description(.0))]\n    Json(#[source] reqwest::Error),\n\n    #[error(\"failed to parse plaintext response: {}\", reqwest_description(.0))]\n    Text(#[source] reqwest::Error),\n\n    #[error(\"server responded with error [{code}]: {message}\")]\n    ApiError {\n        code: StatusCode,\n        message: String,\n        /// Machine-readable error code from JSON error responses, if present.\n        error_code: Option<String>,\n    },\n\n    #[error(\"failed to send {method} {url} request: {}\", reqwest_description(.source))]\n    RequestSend {\n        method: Method,\n        url: String,\n        #[source]\n        source: reqwest::Error,\n    },\n\n    #[error(\"failed to build an http client: {}\", reqwest_description(.0))]\n    Builder(#[source] reqwest::Error),\n","sourceCodeStart":38,"sourceCodeEnd":74,"githubUrl":"https://github.com/influxdata/influxdb/blob/06200ef96ba82c5f6727e5038a83af8e722c6875/influxdb3_client/src/lib.rs#L38-L74","documentation":"Error::ApiError, returned when the InfluxDB 3 server responds with a non-success HTTP status. The variant carries the StatusCode, a human-readable message parsed from the response body, and an optional machine-readable error_code extracted from JSON error responses. This is the server explicitly rejecting the request — not a transport or parsing failure.","triggerScenarios":"Any Client API call where the server returns 4xx/5xx: invalid SQL in a query, unknown database/table, bad write payload, missing or invalid auth token, resource limits exceeded, or server-side internal errors.","commonSituations":"Typo'd SQL or nonexistent database in a query (404/422); expired or wrong token (401/403); malformed line-protocol writes (400); hitting the server during startup or under load (503). Match on error_code for programmatic handling.","solutions":["Read message and error_code fields on the variant to identify the server-side cause","For ApiError with 401/403, fix the token (Authorization: Bearer ...) and its permissions","For 404/422 on queries, verify database name and SQL against the server catalog","For 400 on writes, validate line protocol / payload format before sending","Check server logs for the corresponding request to get full context"],"exampleFix":"// before\nlet resp = client.api_v3_query_sql(sql, ...).await?; // ApiError bubbles up\n// after\nmatch client.api_v3_query_sql(sql, ...).await {\n    Ok(resp) => resp,\n    Err(influxdb3_client::Error::ApiError { code: StatusCode::UNAUTHORIZED, .. }) => {\n        refresh_token_and_retry().await\n    }\n    Err(e) => return Err(e),\n}","handlingStrategy":"type-guard","validationCode":"// before calling: validate SQL/db name client-side\nif db.is_empty() || sql.trim().is_empty() {\n    return Err(\"database and sql are required\");\n}","typeGuard":"fn as_api_error(e: &influxdb3_client::Error)\n    -> Option<(http::StatusCode, &str, Option<&str>)>\n{\n    if let influxdb3_client::Error::ApiError { code, message, error_code } = e {\n        Some((*code, message.as_str(), error_code.as_deref()))\n    } else { None }\n}","tryCatchPattern":"match result {\n    Err(e @ influxdb3_client::Error::ApiError { code, message, error_code }) => {\n        match code {\n            StatusCode::UNAUTHORIZED | StatusCode::FORBIDDEN => reauthenticate().await,\n            StatusCode::TOO_MANY_REQUESTS => backoff_and_retry().await,\n            _ => log::error!(\"api error {code} ({error_code:?}): {message}\"),\n        }\n    }\n    other => other?,\n}","preventionTips":["Check the token's validity and scope before deployment","Validate SQL and database/table names against the server catalog","Match on error_code rather than string-matching messages for programmatic handling","Respect Retry-After on 429 responses"],"tags":["http","api","influxdb3","server-error"],"backgroundTag":"api-error-response","analyzedSha":"06200ef96ba82c5f6727e5038a83af8e722c6875","analyzedAt":"2026-09-19T12:55:30.003Z","contentChangedAt":"2026-09-19T12:55:30.003Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}