跳到主要内容

错误

这是 Kaleidr 平台 API 的完整错误列表。每个错误都包含 HTTP 状态码和一个错误代码，后者是供程序进行分支判断的简短、稳定字符串。仅凭 HTTP 状态码并不足够。403 可能有多种不同原因；429 既可能表示“降低请求频率”，也可能表示“配额已耗尽”。

先了解响应结构，因为错误代码并不总是在同一个字段中。

响应格式​

结构示例适用情况
包装后的错误代码{"detail": "origin_not_allowed"}几乎所有 401、403、404、413、500 和 503 错误、422 请求限制错误代码，以及两种 429 错误（map_load_quota_exceeded 和上传 API 的 ingest_rate_limited）。代码是 detail 字符串。
扁平对象{"error": "rate_limited", "detail": "API key rate limit exceeded. Slow down."}其他所有 429 错误。代码位于 error，detail 是面向用户的说明。配额错误还会包含其他字段。
验证列表{"detail": [{"loc": ["body", "product"], "msg": "…", "type": "…"}]}请求体或查询参数格式错误时的 422 响应。detail 是数组，每个问题对应一项。
HTTP 200 中的错误{"error": "Route planning failed."}仅适用于 POST /chat/control/route。请参见下文。

下面的函数可以从以上任意结构中读取错误代码：

async function kaleidrError(res) {
  const body = await res.json().catch(() => ({}));
  const code =
    typeof body.error === 'string' ? body.error :      // flat 429
    typeof body.detail === 'string' ? body.detail :    // wrapped code
    Array.isArray(body.detail) ? 'validation_error' :  // 422
    'unknown_error';
  return { status: res.status, code, body, retryAfter: Number(res.headers.get('retry-after')) || null };
}

需要关注两个响应头：429 响应中的 Retry-After（以秒为单位），以及可选的 X-Request-Id，后者可在联系支持团队时标识请求。

身份验证：401​

API 不接受此身份凭据。

代码触发条件处理方式
Invalid or missing API key没有发送身份凭据，或者密钥未知、已撤销或已过期。也可能是：会话令牌已过期；会话关联的密钥被撤销或在没有宽限期的情况下轮换；密钥中已移除该会话的来源或产品；会话是在套餐降级前签发的；组织被暂停或没有套餐。在 kaleidr.com/api-keys 检查密钥及其状态。如果是会话，请重新交换令牌。若有效密钥持续失败，请稍后重试：短暂的平台故障也可能返回此错误。
publishable_requires_session将可公开密钥（kld_pk_…）发送到了运行时端点。在浏览器中让 SDK 执行交换，或先调用 POST /sdk/sessions。在后端使用服务器密钥。

授权：403​

API 已识别身份凭据，但拒绝此请求。

代码触发条件处理方式
insufficient_scope密钥创建时没有授予此端点或产品所需的权限范围。使用具有所需权限范围的密钥。不能向现有密钥添加权限范围。
tier_capability_not_allowed密钥具有相应权限范围或产品，但组织的当前套餐不包含它。若已发布地图的所有者套餐不含聊天功能，也会返回此错误。但 vendor 例外：低于 Enterprise 套餐的密钥即使仍带有 vendor 也不会被拒绝，只是回答不会使用组织数据。更换套餐，或使用当前套餐包含的产品。
server_key_in_browser服务器密钥（kld_sk_…）随 Origin 请求头发送。将调用移到后端。如果密钥曾出现在页面源代码中，请轮换该密钥。
session_origin_mismatch会话令牌被用于与签发来源不同的来源，或者在未提供 Origin 的情况下使用已发布地图的会话。在实际使用会话的页面上重新交换。
ip_not_allowed带有 IP 允许列表的服务器密钥或旧版密钥从列表外的地址发起调用，或无法确定调用者地址。从允许的地址调用，或修改密钥的 allowed_ips。
publishable_key_required使用服务器密钥或旧版密钥调用了 POST /sdk/sessions。使用可公开密钥进行交换。
origin_required会话交换请求缺少 Origin 请求头。从浏览器页面执行交换。
origin_not_allowed页面来源不在密钥允许的来源列表内，或不在已发布地图允许的域名列表内。将准确的来源添加到密钥，或将域名添加到地图。
product_not_allowed密钥仅允许某些产品，而请求针对其他产品。在会话交换时：请求的 product 不在可公开密钥的允许产品中。在运行时：服务器密钥或旧版密钥调用了不被允许的产品端点，例如仅允许 tile 的密钥调用 /chat/*。修改 allowed_products，或使用其他密钥。
chat_disabled已发布地图的会话交换：地图的 Kaleidr AI 未开启所请求的功能。在 Studio 中地图的 Kaleidr AI 磁贴里开启 Control Tower 或 Popup Window。
feature_not_granted为弹窗聊天开启的已发布地图会话被用于 /chat/control/stream。每项功能各有独立会话。使用 "feature": "control_tower" 交换会话；地图在 Control Tower 开启时授予该功能。
owner_has_no_organization已发布地图的会话交换：地图所有者没有可承担费用的组织。所有者必须创建或加入组织。

未找到：404​

代码触发条件处理方式
not_found已发布地图的会话交换：没有任何已发布地图或分享链接使用此 share_id。检查 ID，并确认地图已经发布。
sessions_disabled平台已禁用会话交换。你无法自行修改此设置，请联系支持团队。
Not Found路径不存在。根据端点文档检查 URL，包括 /inference-api/b2b/v1 前缀。

验证：422​

请求体或查询字符串不符合端点要求。detail 是一个数组，其中每项的 loc 指明字段，msg 说明错误。

{
  "detail": [
    { "type": "missing", "loc": ["body", "product"], "msg": "Field required", "input": {} }
  ]
}

请修正请求，不要原样重试。两个流式端点 /chat/summary/stream 和 /chat/button/stream 在请求体格式错误时返回 500 而非 422；字段超长的情况除外（见下文）。

请求限制：带代码的 422​

格式正确但超过大小限制的请求也会返回 422，不过采用包装后的结构：detail 是包含错误代码的字符串，而不是数组。此类拒绝不会计费。

{ "detail": "conversation_too_long" }
代码端点触发条件处理方式
too_many_messages/chat/control/streammessages 超过 400 项。只发送最近的对话轮次。
message_too_long/chat/control/stream某条消息的 content 超过 64,000 个字符。缩短该消息。
conversation_too_long/chat/control/stream所有消息的 content 总长度超过 200,000 个字符。删除较早的对话轮次后重新发送。
invalid_session_id/chat/control/streamsession_id 超过 128 个字符，或包含字母、数字、_、.、:、- 之外的字符。使用符合要求的 ID，例如 UUID。
lang_too_long/chat/control/streamlang 超过 35 个字符。发送 pt-BR 之类的 BCP 47 语言标签。
invalid_layout/chat/control/streamlayout 超过 16 个字符。viewer 显示导览布局时发送 guide，或省略该字段。
field_too_long/chat/summary/stream, /chat/button/stream文本字段超过长度限制，或列表项数超过限制。缩短字段。限制详见端点文档。

聊天流的限制详见端点文档。

请求过大：413​

代码触发条件处理方式
request_too_large请求体超过 2 MiB，或 /design/* 端点请求体超过 5 MiB。响应体为 {"detail": "request_too_large"}。不会计费。减少发送量：精简对话，或减少设计请求中的样本行。不要原样重试。
request_body_too_large/shared-api 下的密钥管理或业务数据请求超过 1 MiB，或上传请求 POST /shared-api/datahub/ingests 超过 32 MiB。缩小请求体。上传要求详见上传业务数据。

如果请求声明的大小远超任意端点的限制，它可能在抵达 API 前就被网络边缘拒绝。这类响应没有 Kaleidr JSON 响应体，因此也没有可读取的错误代码；请减少发送量。

因大小而被拒绝的请求与其他在处理前被拒绝的请求一样，不会收费，之后也不会占用 AI 积分或并发名额。

配额和速率限制：429​

决定是否重试之前，请先读取响应体。

代码字段Retry-After发生条件处理方式
quota_exceedederror距离 reset_at 的秒数组织的 AI 积分不足以支付本次调用，或者调用将超出该密钥自身的月度上限。上传 API 的映射方案建议调用也会返回此错误。不要重试。等待至 reset_at、补充积分或提高密钥限额。
rate_limitederror5密钥每分钟允许的请求数已用尽。对于某个密钥、已发布地图或单个地址进行过多次会话交换时也会发生。等待 Retry-After 指定的秒数，然后添加随机延迟再重试。
org_overloadederror5组织同时进行的调用过多。等待某次正在执行的调用结束后重试。关闭不再需要的流式连接。
b2b_overloadederror5API 已达到面向所有调用方的处理容量上限。等待 Retry-After 指定的秒数，然后按逐步增加的退避间隔重试。
limiter_unavailableerror5速率限制器无法响应。稍后重试。这并非由你的请求速率造成。
visitor_limit_reachederror5已发布地图聊天中的某位访客超过了每分钟或每天的请求上限。告知访客稍后再试。
map_load_quota_exceededdetail无针对 tile 的 POST /sdk/sessions：组织的地图加载额度已用尽。不要重试。等待周期重置，或购买额外的地图加载包。

quota_exceeded 响应体包含以下数值：

{
  "error": "quota_exceeded",
  "detail": "Usage limit reached. Please try again later.",
  "product": "b2b",
  "meter": "b2b.tokens",
  "tier": "pro",
  "limit": 5000000,
  "used": 4999100,
  "remaining": 900,
  "reset_at": "2026-11-01T04:00:00+00:00",
  "period": "month",
  "reset_in_seconds": 1296000
}

这是服务器密钥收到的响应体。使用会话令牌（由可公开密钥交换所得，或来自已发布地图的访问者会话）发起的请求会收到更简短的响应体，不会泄露组织的套餐或使用量：

{
  "error": "quota_exceeded",
  "detail": "Usage limit reached. Please try again later.",
  "meter": "b2b.tokens",
  "reset_at": "2026-11-01T04:00:00+00:00",
  "reset_in_seconds": 1296000
}

各字段、单个密钥上限的变体及处理示例代码详见配额与速率限制。

服务器错误：5xx​

状态代码触发条件处理方式
500An internal error occurred. Please try again.发生意外故障。稍等片刻后重试一次。
500map_design_analyze_failedPOST /design/analyze 无法分析表格。不会计费。检查表格列与样本行，然后重试。
500Summary stream errorPOST /chat/summary/stream 无法启动：请求体无法读取，或建筑物请求缺少 address。字段过长时则返回 422 field_too_long。修正请求体。
500Button chat stream errorPOST /chat/button/stream 无法启动：请求体无法读取或缺少 query。字段过长时则返回 422 field_too_long。修正请求体。
503sessions_not_configured平台故障导致会话交换不可用。重试；持续失败时联系支持团队。
503share_grant_unavailable已发布地图的会话交换：无法读取地图设置。稍后重试。

状态码为 200 的错误​

POST /chat/control/route 在无法规划路线时也会返回 200：

{ "error": "Route planning failed." }

此响应包含 error，但没有 action。只检查状态码的客户端会误认为调用成功，随后在读取 action 时失败。请始终检查响应体中的 error。错误文本已适合直接向用户展示。详情见路线指引。

GET /retrieval/geocode/forward 也有类似行为：内部查询失败时返回 200 且 results 为空，这与没有匹配结果的查询相同。

流式传输中的错误​

上述内容均适用于流开始之前：被拒绝的流式请求会收到普通 HTTP 错误。一旦响应状态为 200 且开始传输帧，故障就会通过 error 事件发送：

event: error
data: {"type": "error", "code": "upstream_stall", "message": "The AI service stopped responding. Please try again.", "partial_text": "The Louvre sits"}
流code触发条件处理方式
/chat/control/streamupstream_stall回答停止推进，或流达到约 10 分钟的最长运行时间。提供重试选项。如果 partial_text 有用，请保留它。
/chat/control/stream缺失生成回答期间的其他故障。显示 message。重试可能成功。
/chat/summary/stream缺失摘要生成失败。显示 message，或不显示摘要。
/spot/overview/stream缺失概览失败或无法描述 ref。如果无法描述，事件会携带 ref：不在指定点的 poi: 或 region: 引用、缺少 hint.name 的 place:，或 API 不提供描述的建筑物或地址。不显示概览。对于携带 ref 的事件，不要重试。
/chat/button/stream无此流没有 error 事件。失败时连接会直接关闭，不发送 end。将没有 end 就关闭的流视为失败。

适用于每一种流的规则：

  • error 事件会取代 end。之后最多只会再出现可选的 quota 事件。
  • 如果连接关闭前既没有 end 也没有 error，则视为失败。
  • quota 事件不是错误，而是在 end 或 error 之后发送的用量报告。使用会话令牌读取流时，它仅包含 type、meter 和 reset_at。
  • 未知事件名称不代表错误，应忽略它。

即使流失败或中途关闭，也仍会计费。对于 /chat/control/stream，费用不会低于根据发送的对话内容估算的金额，因此可能高于开始时预留的积分：参见流式调用的计费方式。每次重试都是另一次独立计费的请求。

浏览器隐藏的错误​

当来源或身份凭据被拒绝时，响应不会包含 CORS 响应头，浏览器会阻止代码读取状态和响应体。页面控制台会显示 CORS 错误，fetch 会被拒绝；SDK 会记录包含 [kaleidr:<product>] 的错误。

要读取真实错误代码，请打开 Network 选项卡并选择失败的请求。常见代码包括 origin_not_allowed、Invalid or missing API key 和 server_key_in_browser。参见 CORS 与允许的来源。

没有 Kaleidr JSON 响应体的 4xx 错误来自 API 前面的网络边缘层。原因可能是速率限制（降低请求频率，稍后重试），也可能是声明的请求大小远超所有端点的限制（减少发送量；原样重试会得到相同结果）。

地图瓦片主机​

不通过来自允许来源、使用有效可公开密钥的 Kaleidr 嵌入组件访问 tile.kaleidr.com 时，会收到：

状态代码Retry-After处理方式
429tile_access_restricted（位于 error，并带有 message 和 docs）3600使用带可公开密钥的 Tile 产品。如果密钥设置了允许来源列表，请将页面来源加入列表。

密钥管理​

来自 https://api.kaleidr.com/shared-api/api-keys 的错误。API Keys 页面使用该接口，你也可以通过账号访问令牌调用。所有错误都采用包装后的结构。

状态代码触发条件处理方式
401不固定没有有效的账户访问令牌。这里不接受平台密钥。重新登录。
403org_admin_required账号不是组织的所有者或管理员。联系所有者或管理员。
403plan_required组织没有套餐。前往 kaleidr.com/billing选择套餐。
403free_plan_publishable_only在 Free 套餐下请求创建服务器密钥。Free 套餐轮换服务器密钥或旧版密钥时也会返回。创建可公开密钥，或升级到 Pro。
403tier_capability_not_allowed创建密钥时：scopes 或 allowed_products 包含当前套餐不允许的内容。常见情况是在 Free 或 Pro 下请求 vendor：无论是否提供 vendor_acknowledged 都会被拒绝，也不会创建密钥。编辑密钥时：allowed_products 包含套餐不支持的产品，或在 Free 下设置为空列表。vendor 需要 Enterprise。其他情况下只填写套餐支持的权限范围与产品。
404key_not_found组织中没有该 ID 对应的密钥。编辑与撤销操作可匹配任何状态的密钥，因此重复撤销已撤销的密钥会返回 200。轮换需要有效密钥，对已撤销密钥则返回此错误。检查 ID。轮换时，该密钥可能已被撤销。
409key_limit_reached组织已达到套餐允许的活跃密钥数量（Free 2、Pro 10、Enterprise 25）。撤销一个密钥，或轮换现有密钥，而不是创建新密钥。
409key_already_rotated密钥已轮换，无论宽限期是否结束，都不能再次轮换。尝试清空 expires_at 或将其设置为宽限期结束之后也会被拒绝。仍可设置更早的 expires_at 或编辑其他字段。使用替代密钥。
409key_expired从未轮换的密钥已过期，且编辑请求包含 expires_at。无法为过期密钥设置新的有效期，但仍可编辑其他字段。创建新密钥。
413request_body_too_large请求体超过 1 MiB。缩小请求体。
422unknown_scopescopes 包含 ai、maps、design、vendor 之外的值。修正列表。
422unknown_productallowed_products 包含 chat、editor、viewer、tile 之外的值。修正列表。
422vendor_scope_requires_acknowledgementEnterprise 下请求带 vendor 权限的可公开密钥，但未提供 vendor_acknowledged: true。Free 或 Pro 下同样的请求则返回 403 tier_capability_not_allowed。阅读 vendor 权限范围，然后发送此字段。
422no_fields_to_update编辑请求没有任何可编辑字段。至少发送一个字段。
422验证列表来源、IP 项、过去的到期时间或名称格式错误。修正 loc 指明的字段。
500insert_failed, session_unavailable平台故障。重试。
503api_key_pepper_not_configured平台故障导致无法创建密钥。重试；持续失败请联系支持团队。

业务数据上传​

来自 https://api.kaleidr.com/shared-api/datahub 下的上传路由及字段映射建议调用的错误。完整列表（包括导致各类 422 的文件和字段限制）见上传业务数据。以下列出在读取文件前拒绝请求的错误，以及取消发布或删除数据版本时的错误：

状态代码触发条件处理方式
403org_admin_required账号不是组织所有者或管理员。字段映射建议调用也会返回。联系所有者或管理员。
403vendor_data_not_on_plan组织套餐不支持上传业务数据。此功能仅属于 Enterprise。上传、发布、重新处理和字段映射建议调用会返回；读取、取消发布或删除调用不会返回。升级到 Enterprise。GET /shared-api/datahub/limits 在所有套餐下都能直接返回组织是否具有上传权限，不会因此拒绝请求。Free 和 Pro 用户可改为在 Kaleidr Studio 中向地图添加数据：参见地图中的数据集。
404release_not_found取消发布或删除时，组织中不存在该 ID 的版本，包括已完成删除的版本。如果是在删除操作中，可视为已删除。
409org_ingest_in_progress组织的另一次上传仍在处理。上传、发布和重新处理调用会返回。等待完成后重新发送。
409release_not_published对草稿或失败的版本调用了取消发布。无需取消发布，可直接删除。
409release_is_published尝试删除当前已发布的版本。先取消发布，再删除。
413request_body_too_large上传请求超过 32 MiB。发送更小的文件。文件本身可达到组织的文件大小限制。
422detail 中的 { "errors": [ … ] }文件超过行数或大小限制、JSON 包中的字段超过长度限制，或 JSON 嵌套过深。合同设置的限制所对应的原因中会写明限制值与套餐。阅读各项原因并修正文件。
429ingest_rate_limited组织在最近一小时内启动了 30 次上传。等待后重试。
429detail 中的一句话账号在最近一小时内提出了 30 次字段映射建议。响应体没有 error 字段。等待后重试。
429error 中的 quota_exceeded字段映射建议：组织的 AI 积分已用尽。响应体是标准配额响应。等待 reset_at、补充积分或手动编写字段映射。

在 Kaleidr Studio 中上传数据集​

本节不属于使用密钥认证的平台 API。这里介绍已登录用户在 Kaleidr Studio 的 Data 面板中向地图添加数据集时，因大小限制而被拒绝所收到的响应。不涉及 API 密钥。共有两种含义不同的拒绝情况：

状态代码触发条件处理方式
402quota_exceeded新数据集上传超过组织的某项套餐限制：单个数据集行数、单个文件大小，或组织所有数据集的总行数。limit_key 指明限制。已存储的数据保留。Studio 会显示提示及升级链接。上传更小的文件，或删除不再需要的数据集。Free 可升级到 Pro；Pro 或 Enterprise 可联系 Kaleidr提高组织总量上限，但单个数据集行数及单个文件大小不可超过下一行的硬性上限。
400VALIDATION_ERROR文件或数据集超过适用于所有套餐的硬性上限：文件大于 64 MiB、数据集超过 100,000 行、地理文件超过 50,000 个要素，或图片叠加层大于 16 MiB。代码位于 error。升级套餐也不能通过此上传。将文件拆分为更小的文件。不要原样重试，也不要提供升级方案。

收到哪种响应取决于大小，而不只是套餐。系统会先检查硬性上限，因此文件超过 64 MiB 或数据集超过 100,000 行时，Free、Pro、Enterprise 都返回 400。402 表示上传未超过硬性上限，但超过组织自身的限制，例如 Free 套餐文件限制为 32 MiB，却上传了 40 MiB 文件。

402 quota_exceeded​

响应体是问题详情对象，还包含 Studio 自身的 error 和 message 字段。代码同时位于 error 与 code，提示文字同时位于 message 与 detail：

{
  "error": "quota_exceeded",
  "message": "Your plan allows 250,000 rows across all of your organization's datasets. Delete a dataset or upgrade to add more.",
  "type": "https://errors.kaleidr.com/datasets/quota_exceeded",
  "title": "Quota Exceeded",
  "status": 402,
  "detail": "Your plan allows 250,000 rows across all of your organization's datasets. Delete a dataset or upgrade to add more.",
  "code": "quota_exceeded",
  "limit_key": "studio.data.rows.max",
  "limit": 250000,
  "used": 248500,
  "tier": "free",
  "upgrade_url": "https://kaleidr.com/pricing"
}
字段含义
error, code始终为 quota_exceeded，同一个值出现两次。
message, detail同一句话出现两次。它用易懂的语言说明限制，可直接向用户显示。
type始终为 https://errors.kaleidr.com/datasets/quota_exceeded。
title始终为 Quota Exceeded。
status始终为 402。
limit_key导致上传被拒绝的限制。见下表。
limit组织限制数值，单位与该限制一致。
used对总量限制，表示组织已存储的行数；另外两种限制表示此次上传的行数或 MiB。
tier组织套餐：free、pro 或 enterprise。读取套餐失败时为 unknown，此时使用 Free 限制。
upgrade_url更换套餐的网址。
limit_key限制limit 和 used 的单位提示语
studio.dataset.rows.max单个数据集行数行“您的套餐允许单个数据集最多 50,000 行。请上传更小的文件或升级套餐。”
studio.dataset.file.mb单个上传文件大小MiB“您的套餐支持不超过 32 MB 的文件。请上传更小的文件或升级套餐。”
studio.data.rows.max组织所有数据集总行数行“您的套餐允许组织所有数据集合计 250,000 行。请删除一个数据集或升级套餐以继续添加。”

这些句子中的数值是 Free 套餐限制；实际收到的句子会使用你所在组织的限制。请向用户展示句子，并依据 code 和 limit_key 执行分支处理。此 402 与平台 API 中关于 AI 积分的 429 quota_exceeded 是不同的响应。

400 VALIDATION_ERROR​

响应体只有两个字段，没有问题详情的其他成员：

{
  "error": "VALIDATION_ERROR",
  "message": "File is larger than 64 MB."
}
拒绝原因message
文件超过 64 MiB“文件大于 64 MB。”
数据集超过 100,000 行“每个数据集最多 100000 条记录”
地理文件超过 50,000 个要素“<filename> 包含超过 50000 个要素。请在上传前拆分文件或简化几何形状。”
图片叠加层超过 16 MiB“叠加层图像大于 16 MB。”

上传文件的其他问题（例如 Studio 不支持的文件类型，或文件没有可用行）也会返回相同状态和代码；message 会说明具体原因。应将任何上传时的 400 视为“该文件无法按当前形式添加”，并显示 message。

相关内容​