오류

Kaleidr 플랫폼 API에서 반환할 수 있는 전체 오류 목록입니다. 각 오류에는 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`은 문제당 하나의 항목을 가진 배열입니다.
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`에서 사용되었습니다. 기능마다 별도의 세션이 있습니다.	지도가 Control Tower를 켜 둔 동안 부여하는 `"feature": "control_tower"`로 세션을 교환하세요.
`owner_has_no_organization`	게시 지도 세션 교환: 지도 소유자에게 비용을 청구할 조직이 없습니다.	소유자가 조직을 만들거나 기존 조직에 참여해야 합니다.

찾을 수 없음: 404

코드	발생 조건	해결 방법
`not_found`	게시 지도 세션 교환: 이 `share_id`를 가진 게시 지도나 공유 링크가 없습니다.	ID와 지도 게시 여부를 확인하세요.
`sessions_disabled`	플랫폼에서 세션 교환이 꺼져 있습니다.	사용자가 변경할 수 없습니다. 지원팀에 문의하세요.
`Not Found`	경로가 존재하지 않습니다.	`/inference-api/b2b/v1` 접두사를 포함해 엔드포인트의 URL과 비교하세요.

유효성 검사: 422

요청 본문이나 쿼리 문자열이 엔드포인트에서 허용하는 형식과 일치하지 않습니다. detail은 배열이며 각 항목의 loc는 필드를, msg는 잘못된 내용을 나타냅니다.

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

요청을 수정하세요. 같은 요청을 변경 없이 다시 보내지 마세요. 스트리밍 엔드포인트 /chat/summary/stream과 /chat/button/stream은 본문 형식이 잘못된 경우 필드 길이 초과를 제외하고 422 대신 500을 반환합니다(아래 참조).

요청 제한: 코드가 포함된 422

형식이 올바르더라도 크기 제한을 넘는 요청은 422를 반환합니다. 다만 래핑 형식을 사용하여 detail이 배열이 아닌 코드 문자열이 됩니다. 과금되지 않습니다.

{ "detail": "conversation_too_long" }

코드	엔드포인트	발생 조건	해결 방법
`too_many_messages`	`/chat/control/stream`	`messages`가 400개를 초과합니다.	가장 최근 대화 턴만 보내세요.
`message_too_long`	`/chat/control/stream`	한 메시지의 `content`가 64,000자를 초과합니다.	메시지를 줄이세요.
`conversation_too_long`	`/chat/control/stream`	모든 메시지의 `content` 합계가 200,000자를 초과합니다.	오래된 턴을 제거한 뒤 다시 보내세요.
`invalid_session_id`	`/chat/control/stream`	`session_id`가 128자를 초과하거나 영문자, 숫자, `_`, `.`, `:`, `-` 이외의 문자를 포함합니다.	UUID처럼 지정된 형식의 ID를 사용하세요.
`lang_too_long`	`/chat/control/stream`	`lang`이 35자를 초과합니다.	`pt-BR`과 같은 BCP 47 언어 태그를 보내세요.
`invalid_layout`	`/chat/control/stream`	`layout`이 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_exceeded`	`error`	`reset_at`까지의 초	조직의 AI 크레딧이 호출을 처리하기에 부족하거나 키 자체의 월간 한도를 초과하게 되는 경우입니다. 업로드 API의 매핑 제안 호출에서도 반환됩니다.	재시도하지 마세요. `reset_at`까지 기다리거나, 크레딧을 추가하거나, 키의 한도를 높이세요.
`rate_limited`	`error`	`5`	키의 분당 요청 한도가 소진된 경우입니다. 키, 게시된 지도 또는 하나의 주소에 대해 세션 교환이 너무 많이 발생한 경우도 해당합니다.	`Retry-After`에 지정된 초만큼 기다린 다음 무작위 지연을 더해 재시도하세요.
`org_overloaded`	`error`	`5`	조직에서 동시에 처리 중인 호출이 너무 많습니다.	진행 중인 호출이 끝날 때까지 기다린 뒤 재시도하세요. 더 이상 필요하지 않은 스트림은 닫으세요.
`b2b_overloaded`	`error`	`5`	전체 호출자에 대해 API가 처리 용량 한도에 도달했습니다.	`Retry-After`에 지정된 초만큼 기다린 뒤 재시도 간 대기 시간을 점차 늘리며 다시 시도하세요.
`limiter_unavailable`	`error`	`5`	요청 속도 제한기가 응답하지 못했습니다.	잠시 후 재시도하세요. 요청 빈도 때문에 발생한 문제가 아닙니다.
`visitor_limit_reached`	`error`	`5`	게시된 지도의 채팅에서 방문자 한 명이 분당 또는 일일 요청 한도를 초과했습니다.	방문자에게 나중에 다시 시도하라고 안내하세요.
`map_load_quota_exceeded`	`detail`	없음	`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

상태	코드	발생 조건	해결 방법
500	`An internal error occurred. Please try again.`	예상치 못한 오류입니다.	잠시 기다린 뒤 한 번 다시 시도하세요.
500	`map_design_analyze_failed`	`POST /design/analyze`가 테이블을 분석하지 못했습니다. 과금되지 않습니다.	테이블의 열과 샘플 행을 확인한 뒤 다시 시도하세요.
500	`Summary stream error`	`POST /chat/summary/stream`을 시작하지 못했습니다. 본문을 읽을 수 없거나 건물 요청에 `address`가 없습니다. 너무 긴 필드는 대신 422 `field_too_long`을 반환합니다.	본문을 수정하세요.
500	`Button chat stream error`	`POST /chat/button/stream`을 시작하지 못했습니다. 본문을 읽을 수 없거나 `query`가 없습니다. 너무 긴 필드는 대신 422 `field_too_long`을 반환합니다.	본문을 수정하세요.
503	`sessions_not_configured`	플랫폼 오류로 세션 교환을 사용할 수 없습니다.	다시 시도하고 문제가 지속되면 지원팀에 문의하세요.
503	`share_grant_unavailable`	게시 지도 세션 교환: 지도 설정을 읽을 수 없습니다.	잠시 후 다시 시도하세요.

상태 코드 200의 오류

POST /chat/control/route는 경로를 계획할 수 없는 경우에도 200을 반환합니다:

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

응답에는 error가 있고 action은 없습니다. 상태 코드만 확인하는 클라이언트는 성공으로 판단한 뒤 action을 읽다가 실패합니다. 본문에 error가 있는지 항상 확인하세요. 오류 텍스트는 사용자에게 표시할 수 있도록 작성되었습니다. 자세한 내용은 길찾기를 참조하세요.

GET /retrieval/geocode/forward도 비슷합니다. 내부적으로 조회가 실패하면 일치하는 결과가 없는 경우와 마찬가지로 빈 results 목록과 함께 200을 반환합니다.

스트림 오류

위의 내용은 스트림 시작 전에 적용됩니다. 거부된 스트리밍 요청은 일반 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/stream`	`upstream_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`	해결 방법
429	`tile_access_restricted` (`message`, `docs`와 함께 `error`에 포함)	`3600`	게시 가능 키를 사용해 Tile 제품을 구성하고, 키에 허용된 출처 목록이 있다면 페이지의 출처를 추가하세요.

키 관리

API Keys 페이지에서 사용하는 https://api.kaleidr.com/shared-api/api-keys의 오류입니다. 계정 액세스 토큰으로 직접 호출할 수도 있습니다. 모든 오류는 코드가 감싸진 형식을 사용합니다.

상태	코드	발생 조건	해결 방법
401	다양함	유효한 계정 액세스 토큰이 없습니다. 플랫폼 키는 허용되지 않습니다.	다시 로그인하세요.
403	`org_admin_required`	계정이 조직 소유자 또는 관리자가 아닙니다.	소유자나 관리자에게 요청하세요.
403	`plan_required`	조직에 요금제가 없습니다.	kaleidr.com/billing에서 요금제를 선택하세요.
403	`free_plan_publishable_only`	Free 요금제에서 서버 키 생성을 요청했습니다. Free에서 서버 키나 레거시 키를 교체할 때도 반환됩니다.	게시 가능 키를 만들거나 Pro로 변경하세요.
403	`tier_capability_not_allowed`	키 생성 시 `scopes` 또는 `allowed_products`에 요금제가 허용하지 않는 항목을 지정했습니다. 주로 Free나 Pro에서 `vendor` 범위를 요청할 때 발생하며 `vendor_acknowledged`를 전송해도 거부되고 키는 생성되지 않습니다. 키 수정 시 `allowed_products`에 요금제가 포함하지 않는 제품을 지정하거나 Free에서 빈 목록을 설정한 경우도 해당됩니다.	`vendor`에는 Enterprise가 필요합니다. 그 밖에는 요금제가 허용하는 범위와 제품만 지정하세요.
404	`key_not_found`	조직에 해당 ID의 키가 없습니다. 수정과 폐기는 모든 상태의 키를 찾으므로 이미 폐기된 키를 다시 폐기해도 200을 반환합니다. 교체는 활성 키가 필요하며 폐기된 키에는 이 코드를 반환합니다.	ID를 확인하세요. 교체 대상 키가 폐기되었을 수 있습니다.
409	`key_limit_reached`	조직의 활성 키가 요금제 한도(Free 2개, Pro 10개, Enterprise 25개)에 도달했습니다.	키를 폐기하거나 새 키 생성 대신 기존 키를 교체하세요.
409	`key_already_rotated`	유예 기간 종료 여부와 관계없이 이미 교체된 키입니다. 다시 교체할 수 없고, `expires_at`을 삭제하거나 유예 기간 종료보다 늦게 설정하는 수정도 거부됩니다. 더 이른 `expires_at`과 다른 필드는 수정할 수 있습니다.	새로 발급된 대체 키를 사용하세요.
409	`key_expired`	교체된 적 없는 키가 만료되었고 수정 요청에 `expires_at`이 포함되었습니다. 만료된 키에는 새 만료일을 지정할 수 없지만 다른 필드는 여전히 수정할 수 있습니다.	새 키를 생성하세요.
413	`request_body_too_large`	요청 본문이 1 MiB를 초과합니다.	더 작은 본문을 보내세요.
422	`unknown_scope`	`scopes`에 `ai`, `maps`, `design`, `vendor` 이외의 값이 있습니다.	목록을 수정하세요.
422	`unknown_product`	`allowed_products`에 `chat`, `editor`, `viewer`, `tile` 이외의 값이 있습니다.	목록을 수정하세요.
422	`vendor_scope_requires_acknowledgement`	Enterprise에서 `vendor` 범위가 있는 게시 가능 키를 요청하면서 `vendor_acknowledged: true`를 제공하지 않았습니다. Free와 Pro의 같은 요청은 403 `tier_capability_not_allowed`를 반환합니다.	`vendor` 범위를 읽고 해당 필드를 보내세요.
422	`no_fields_to_update`	수정 요청에 수정 가능한 필드가 없습니다.	필드를 하나 이상 보내세요.
422	유효성 검사 목록	출처나 IP 입력 형식이 잘못되었거나 만료일이 과거이거나 이름이 유효하지 않습니다.	`loc`에 표시된 필드를 수정하세요.
500	`insert_failed`, `session_unavailable`	플랫폼 오류입니다.	재시도하세요.
503	`api_key_pepper_not_configured`	플랫폼 문제로 키를 생성할 수 없습니다.	재시도하고 문제가 지속되면 지원팀에 문의하세요.

비즈니스 데이터 업로드

https://api.kaleidr.com/shared-api/datahub의 업로드 경로 및 매핑 제안 호출에서 발생하는 오류입니다. 파일 및 필드 한도로 인한 422를 포함한 전체 목록은 비즈니스 데이터 업로드에 있습니다. 아래에는 파일을 읽기 전에 요청을 거부하는 오류와 릴리스 게시 취소·삭제 호출 오류를 정리했습니다:

상태	코드	발생 조건	해결 방법
403	`org_admin_required`	계정이 조직 소유자 또는 관리자가 아닙니다. 매핑 제안 호출에서도 반환됩니다.	소유자 또는 관리자에게 요청하세요.
403	`vendor_data_not_on_plan`	조직 요금제에서 비즈니스 데이터 업로드를 허용하지 않습니다. 업로드는 Enterprise 전용입니다. 업로드, 게시, 재처리 및 매핑 제안 호출에서 반환되며 조회, 게시 취소, 삭제에서는 반환되지 않습니다.	Enterprise로 변경하세요. `GET /shared-api/datahub/limits`는 모든 요금제에서 거부 없이 업로드 가능 여부를 알려줍니다. Free와 Pro에서는 대신 Kaleidr Studio 지도에 데이터를 추가하세요. 지도의 데이터셋을 참조하세요.
404	`release_not_found`	게시 취소 또는 삭제 시 조직에 해당 ID의 릴리스가 없습니다. 삭제가 완료된 릴리스도 포함됩니다.	삭제 작업이었다면 이미 처리된 것으로 간주하세요.
409	`org_ingest_in_progress`	조직의 다른 업로드가 처리 중입니다. 업로드, 게시 및 재처리 호출에서 반환됩니다.	기존 처리가 끝난 뒤 다시 요청하세요.
409	`release_not_published`	초안 또는 실패한 릴리스에서 게시 취소를 호출했습니다.	취소할 게시가 없습니다. 대신 삭제하세요.
409	`release_is_published`	게시 중인 릴리스에서 삭제를 호출했습니다.	게시를 취소한 뒤 삭제하세요.
413	`request_body_too_large`	업로드 요청이 32 MiB보다 큽니다.	더 작은 파일을 보내세요. 파일 자체는 조직의 크기 제한 이내여야 합니다.
422	`detail`의 `{ "errors": [ … ] }`	파일이 행 수나 크기 제한을 초과했거나 JSON 묶음의 필드가 너무 길거나 JSON 중첩 깊이가 너무 깊습니다. 계약에 따른 한도 사유에는 요금제와 한도가 명시됩니다.	각 사유를 확인하고 파일을 수정하세요.
429	`ingest_rate_limited`	조직이 지난 1시간 동안 업로드 30개를 시작했습니다.	기다린 다음 재요청하세요.
429	`detail`의 문장	계정이 지난 1시간 동안 매핑 제안을 30회 요청했습니다. 본문에 `error` 필드는 없습니다.	기다린 다음 재요청하세요.
429	`error`의 `quota_exceeded`	매핑 제안: 조직의 AI 크레딧을 모두 사용했습니다. 본문은 표준 할당량 형식입니다.	`reset_at`까지 기다리거나 크레딧을 추가하거나 매핑을 직접 작성하세요.

Kaleidr Studio의 데이터 세트 업로드

이 절은 키로 인증하는 플랫폼 API가 아닙니다. 로그인한 사용자가 Kaleidr Studio의 데이터 패널에서 지도에 데이터셋을 추가할 때 크기 때문에 업로드가 거부되는 경우를 설명합니다. API 키는 사용되지 않습니다. 두 가지 거부 유형의 의미는 다릅니다:

상태	코드	발생 조건	해결 방법
402	`quota_exceeded`	새로운 데이터셋 업로드가 조직의 요금제 한도를 초과했습니다. 데이터셋 하나의 행 수, 파일 하나의 크기 또는 조직 전체 데이터셋의 총 행 수에 해당합니다. `limit_key`가 위반된 제한을 나타냅니다. 이미 저장된 데이터는 유지됩니다. Studio는 업그레이드 링크와 함께 메시지를 표시합니다.	더 작은 파일을 업로드하거나 필요 없는 데이터셋을 삭제하세요. Free에서는 Pro로 변경하세요. Pro 또는 Enterprise에서는 조직 전체 한도를 높이기 위해 Kaleidr에 문의하세요. 데이터셋당 행 수와 파일당 크기는 다음 행의 상한을 초과해 높일 수 없습니다.
400	`VALIDATION_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는 AI 크레딧에 관한 플랫폼 API의 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를 표시하세요.

응답 형식​

인증: 401​

인가: 403​

찾을 수 없음: 404​

유효성 검사: 422​

요청 제한: 코드가 포함된 422​

요청 크기 초과: 413​

할당량 및 속도 제한: 429​

서버 오류: 5xx​

상태 코드 200의 오류​

스트림 오류​

브라우저가 숨기는 오류​

타일 호스트​

키 관리​

비즈니스 데이터 업로드​

Kaleidr Studio의 데이터 세트 업로드​

402 quota_exceeded​

400 VALIDATION_ERROR​

관련 문서​