服务：storagebatchoperations.googleapis.com
遇到错误时，请参考此目录并使用我们的客户端库。如果您使用的是自己的库，请随时参考本指南，以便进行调试和解决错误。如需详细了解错误响应结构，请访问错误概览页面。
错误代码
下表列出了您在与我们的 API 互动时可能会遇到的 HTTP 状态代码和相关错误。每个状态代码都对应一个或多个原因和说明，可帮助您在应用中有效排查和处理错误。在说明中，用大括号 ({}) 表示的变量是特定于您的请求的值的占位符。
| 原因 | HTTP 状态代码 | 说明 |
|---|---|---|
JOB_ID_INVALID |
400 |
“job_id”无效。作业 ID 必须与模式 [a-z0-9]([-a-z0-9]*[a-z0-9])? 匹配。如需了解详情，请参阅我们的问题排查文档。 |
RESOURCE_NAME_TOO_LONG |
400 |
资源名称超出了允许的最大长度（{max_length} 字节）。如需了解详情，请参阅我们的问题排查文档。 |
DESCRIPTION_TOO_LONG |
400 |
作业“说明”超出了允许的最大长度（{max_length} 字节）。如需了解详情，请参阅我们的问题排查文档。 |
SOURCE_NOT_SPECIFIED |
400 |
必须为作业指定来源（“bucket_list”或“project_source”）。如需了解详情，请参阅我们的问题排查文档。 |
TRANSFORMATION_NOT_SPECIFIED |
400 |
必须为作业指定转换。指定一项转换：“delete_object”“put_object_hold”“put_metadata”“rewrite_object”“update_object_custom_context”“set_object_acls”或“drop_object_google_context”。如需了解详情，请参阅我们的问题排查文档。 |
BUCKET_LIST_EMPTY |
400 |
“bucket_list”不得为空。请至少指定一个分桶配置。如需了解详情，请参阅我们的问题排查文档。 |
TOO_MANY_BUCKETS |
400 |
“bucket_list”不得超过 {max_buckets} 个存储分区。如需了解详情，请参阅我们的问题排查文档。 |
BUCKET_NAME_REQUIRED |
400 |
必须在存储桶配置中指定“bucket”字段。如需了解详情，请参阅我们的问题排查文档。 |
OBJECT_CONFIGURATION_REQUIRED |
400 |
必须在存储桶操作中指定对象配置（“prefix_list”“manifest”或“project_source”）。如需了解详情，请参阅我们的问题排查文档。 |
MANIFEST_LOCATION_REQUIRED |
400 |
必须指定“manifest_location”字段。如需了解详情，请参阅我们的问题排查文档。 |
MANIFEST_LOCATION_INVALID |
400 |
清单位置“{manifest_location}”无效。位置必须采用 gs://<bucket_name>/<path>/<object_name>.csv 格式，其中 <path> 是可选的，<object_name> 后面跟的是 .csv，并且最多包含一个通配符 (*)。如需了解详情，请参阅我们的问题排查文档。 |
BUCKET_NAME_INVALID |
400 |
存储桶名称“{bucket_name}”不符合 Cloud Storage 存储桶命名要求。如需了解详情，请参阅我们的问题排查文档。 |
OBJECT_NAME_INVALID |
400 |
对象名称“{object_name}”不符合 Cloud Storage 对象命名要求。如需了解详情，请参阅我们的问题排查文档。 |
OBJECT_PREFIX_INVALID_UTF8 |
400 |
对象前缀包含无效的 UTF-8 字符。确保前缀是有效的 UTF-8。如需了解详情，请参阅我们的问题排查文档。 |
OBJECT_PREFIX_TOO_LONG |
400 |
对象前缀超出了允许的最大长度（{max_length} 字节）。如需了解详情，请参阅我们的问题排查文档。 |
OBJECT_PREFIX_INVALID_CHARACTER |
400 |
对象前缀包含无效的换行符或回车符。如需了解详情，请参阅我们的问题排查文档。 |
OBJECT_PREFIX_OVERLAP |
400 |
对象前缀“{prefix_1}”与“{prefix_2}”重叠。对象前缀不得是其他包含的前缀的前缀。如需了解详情，请参阅我们的问题排查文档。 |
DUPLICATE_OBJECT_PREFIX |
400 |
在“included_object_prefixes”中发现了重复的对象前缀“{object_prefix}”。移除重复的条目。如需了解详情，请参阅我们的问题排查文档。 |
TOO_MANY_OBJECT_PREFIXES |
400 |
“prefix_list”不得超过 {max_prefixes} 个包含的对象前缀。如需了解详情，请参阅我们的问题排查文档。 |
PROJECT_SOURCE_DRY_RUN_ID_INVALID |
400 |
“dry_run_job_id”无效。作业 ID 必须与模式 [a-z0-9]([-a-z0-9]*[a-z0-9])? 匹配。如需了解详情，请参阅我们的问题排查文档。 |
PROJECT_SOURCE_DRY_RUN_FIELDS_EXCLUSIVE |
400 |
指定“dry_run_job_id”后，“ProjectSource”中的所有其他字段都必须为空。如需了解详情，请参阅我们的问题排查文档。 |
PROJECT_SOURCE_PROJECT_INVALID |
400 |
项目“{project}”无效。项目必须采用“projects/{project_number}”或“projects/{project_id}”格式。如需了解详情，请参阅我们的问题排查文档。 |
INSIGHTS_DATASET_CONFIG_INVALID |
400 |
数据洞见数据集配置“{insights_dataset_config}”无效。配置资源名称必须采用“projects/{project}/locations/{location}/datasetConfigs/{dataset_config}”格式。如需了解详情，请参阅我们的问题排查文档。 |
TARGET_LOCATIONS_REQUIRED_FOR_SNAPSHOT_TIME |
400 |
提供“snapshot_time”时，必须指定“target_locations”中的“locations”字段。如需了解详情，请参阅我们的问题排查文档。 |
TOO_MANY_TARGET_LOCATIONS |
400 |
“target_locations”列表不得超过 {max_locations} 个位置。如需了解详情，请参阅我们的问题排查文档。 |
CEL_EXPRESSION_TOO_LONG |
400 |
过滤表达式不得超过 {max_length} 字节。如需了解详情，请参阅我们的问题排查文档。 |
KMS_KEY_INVALID |
400 |
KMS 密钥无效。密钥必须采用“projects/{project}/locations/{location}/keyRings/{keyring}/cryptoKeys/{key}”格式。如需了解详情，请参阅我们的问题排查文档。 |
REWRITE_OBJECT_MISSING_PARAMETERS |
400 |
必须为“RewriteObject”指定“storage_class”或“kms_key”中的至少一个。如需了解详情，请参阅我们的问题排查文档。 |
PUT_OBJECT_HOLD_MISSING_PARAMETERS |
400 |
必须至少指定“temporary_hold”或“event_based_hold”之一。如需了解详情，请参阅我们的问题排查文档。 |
PUT_METADATA_MISSING_PARAMETERS |
400 |
必须指定“PutMetadata”中的至少一个字段。如需了解详情，请参阅我们的问题排查文档。 |
RETAIN_UNTIL_TIME_REQUIRED |
400 |
设置“retention_mode”时，必须以 RFC 3339 格式指定“retain_until_time”字段。如需了解详情，请参阅我们的问题排查文档。 |
RETENTION_MODE_REQUIRED |
400 |
“retention_mode”字段必须设置为“LOCKED”或“UNLOCKED”。如需了解详情，请参阅我们的问题排查文档。 |
RETAIN_UNTIL_TIME_INVALID_FORMAT |
400 |
“retain_until_time”字段必须采用 RFC 3339 时间戳格式（例如“2026-12-31T23:59:59Z”）。如需了解详情，请参阅我们的问题排查文档。 |
CUSTOM_CONTEXT_KEY_CONFLICT |
400 |
不能在“updates”和“keys_to_clear”中指定相同的键。如需了解详情，请参阅我们的问题排查文档。 |
UPDATE_OBJECT_CUSTOM_CONTEXT_MISSING_ACTION |
400 |
必须在“UpdateObjectCustomContext”中指定至少一项操作。如果指定了“clear_all”，则必须将其设置为 true。如需了解详情，请参阅我们的问题排查文档。 |
SET_OBJECT_ACLS_MISSING_ACTION |
400 |
必须在“SetObjectAcls”中指定“grants”或“remove_entities”中的至少一个。如需了解详情，请参阅我们的问题排查文档。 |
UNSUPPORTED_ACL_ENTITY |
400 |
不支持实体“{entity}”。仅支持“allUsers”和“allAuthenticatedUsers”。如需了解详情，请参阅我们的问题排查文档。 |
ACL_ENTITY_CONFLICT |
400 |
同一实体不能同时在“grants”和“remove_entities”中指定。如需了解详情，请参阅我们的问题排查文档。 |
AUTOCLASS_STORAGE_CLASS_TRANSFORMATION_UNSUPPORTED |
400 |
无法对启用了 Autoclass 的存储分区执行存储类别转换。停用存储桶上的 Autoclass 或移除存储类别转换。如需了解详情，请参阅我们的问题排查文档。 |
UBLA_OBJECT_ACL_UPDATE_UNSUPPORTED |
400 |
无法更新已启用统一存储桶级访问权限的存储桶中对象的访问权限控制列表 (ACL)。请改用 IAM 权限管理访问权限。如需了解详情，请参阅我们的问题排查文档。 |
BUCKET_DISCOVERY_INSIGHTS_DATASET_NOT_FOUND |
404 |
未能执行存储桶发现。找不到“insights_dataset_config”。验证洞见数据集是否存在且可访问。如需了解详情，请参阅我们的问题排查文档。 |
BUCKET_DISCOVERY_SNAPSHOT_TOO_OLD |
400 |
未能执行存储桶发现。最新的数据集快照时间已超过 2 天。验证数据集配置是否处于有效状态并正在生成快照，指定“snapshot_time”和“target_locations”替换项，或改用 CSV 清单。如需了解详情，请参阅我们的问题排查文档。 |
BUCKET_DISCOVERY_TOO_MANY_BUCKETS |
400 |
未能执行存储桶发现。发现的存储分区过多。仅支持 1,000 个分桶。如需了解详情，请参阅我们的问题排查文档。 |