에러 코드

실패한 요청은 HTTP 상태와 함께 다음 본문을 돌려줍니다.

{ "error": { "code": "INSUFFICIENT_SCOPE", "message": "api key requires scope 'write'" } }

message 는 개발자용 설명이라 바뀔 수 있습니다. 코드는 바뀌지 않으니 분기는 code 로 하세요. 일부 에러는 추가 필드(예: INVALID_LABELS 의 unknown_keys)를 함께 싣습니다.

코드 목록

코드	상태	뜻과 대처
UNAUTHORIZED	401	Key 가 없거나 틀렸습니다. Key 로 열리지 않은 요청을 Key 로 불러도 이 코드입니다.
API_KEY_REVOKED	401	폐기된 Key 입니다. 새 Key 를 발급하세요.
API_KEY_EXPIRED	401	만료된 Key 입니다. 새 Key 를 발급하세요.
AGENT_KEY_REVOKED	401	회수된 AI 에이전트 키입니다. 운영자에게 에이전트 상태를 확인하세요.
TOKEN_REVOKED	401	끊긴 CLI·AI 코딩 툴 연결의 토큰입니다. 그 도구에서 다시 로그인(연결)하세요.
TOKEN_EXPIRED	401	만료된 CLI·AI 코딩 툴 토큰입니다. CLI 와 AI 코딩 툴은 스스로 갱신합니다 — 직접 부를 때는 refresh 토큰으로 새 토큰을 받으세요.
FORBIDDEN	403	권한이 없습니다. Key 를 발급한 사람이 워크스페이스를 떠났을 때도 이 코드입니다.
ACCOUNT_SUSPENDED	403	Key 를 발급한 사람의 계정이 정지됐습니다.
ACCOUNT_DELETION_PENDING	403	Key 를 발급한 사람의 계정이 삭제 예정입니다(유예 중). 그 사람이 다시 로그인해 삭제를 취소하면 Key 가 다시 동작합니다.
ACCOUNT_DELETED	403	Key 를 발급한 사람의 계정이 삭제됐습니다. 이 Key 는 다시 동작하지 않습니다 — 다른 사람이 새 Key 를 발급하세요.
INSUFFICIENT_SCOPE	403	Key 에 이 요청에 필요한 권한(read·write·metrics:ingest)이 없습니다.
WORKSPACE_MISMATCH	403	x-workspace-slug 헤더가 Key 의 워크스페이스와 다릅니다. 헤더를 빼거나 맞추세요.
DEV_TOOLS_DISABLED_FOR_WORKSPACE	403	워크스페이스 관리자가 이 워크스페이스의 개발 도구 연결(CLI·AI 코딩 툴)을 꺼 두었거나, 이 CLI 로그인을 이 워크스페이스에서 끊었습니다. 개인 키(gtk_)로 부르는 REST 요청은 그대로 됩니다.
WRITER_ROLE_REQUIRED	403	Key 를 발급한 사람(에이전트 키는 그 에이전트)이 지금 보기 권한(viewer)이라 쓸 수 없습니다.
AGENT_NOT_ASSIGNED	403	이 이슈는 이 AI 에이전트에게 배정되지 않았습니다. 에이전트 키는 배정된 이슈에만 씁니다. 읽기는 됩니다.
WORKSPACE_SUSPENDED_FULL	403	워크스페이스가 정지돼 읽기·쓰기가 모두 막혔습니다. 워크스페이스 관리자에게 문의하세요.
WORKSPACE_SUSPENDED_READ_ONLY	403	워크스페이스가 읽기 전용으로 정지됐습니다. 읽기는 되고 쓰기는 막힙니다.
SYSTEM_SOURCE_FORBIDDEN	403	Key 로는 source: "system_etl" 값을 넣을 수 없습니다. source 를 빼세요.
VALIDATION	400	본문이나 쿼리가 형식에 맞지 않습니다. 모르는 필드가 있어도 이 코드입니다.
WORKSPACE_REQUIRED	400	CLI 로그인 토큰은 여러 워크스페이스에 쓰여서, 요청마다 워크스페이스를 골라야 합니다. x-workspace-slug 헤더(CLI 는 -W <slug>)를 주세요.
INVALID_LABELS	400	지표에 없는 차원을 labels 에 넣었습니다. unknown_keys 를 확인하세요.
METRIC_LABEL_EMPTY	400	labels 의 값이 비었거나 공백뿐입니다. empty_keys 의 차원에 값을 넣거나 그 키를 빼세요.
REF_NOT_IN_WORKSPACE	400	팀·프로젝트 같은 참조가 이 워크스페이스의 것이 아닙니다(field 에 칸 이름).
NOT_IN_WORKSPACE	400	이슈를 만들 때 고른 라벨(label_ids) 중 이 워크스페이스에 없는 것이 있습니다(field 에 칸 이름). 하나라도 없으면 이슈를 만들지 않습니다.
LABEL_IS_GROUP	400	label_ids 에 라벨 그룹 자체가 들어 있습니다. 그룹은 붙일 수 없으니 그룹 안의 라벨을 고르세요.
LABEL_GROUP_EXCLUSIVE	400	label_ids 에 같은 라벨 그룹의 라벨이 둘 이상 있습니다. 그룹마다 하나만 고르세요(group_id 에 그 그룹).
INVALID_PARENT	400	상위 이슈(parent_id)를 그 자리에 둘 수 없습니다(다른 팀이거나 상위를 가질 수 없는 이슈). reason 을 확인하세요.
CYCLE_IN_OTHER_TEAM	400	고른 사이클이 이슈와 다른 팀의 것입니다. 이슈와 같은 팀의 사이클을 고르세요.
MILESTONE_NOT_IN_PROJECT	400	고른 마일스톤이 이슈의 프로젝트 것이 아닙니다(이슈에 프로젝트가 없는 경우 포함). 이슈의 프로젝트를 정하고 그 프로젝트의 마일스톤을 고르세요. 프로젝트만 바꾸면 맞지 않는 마일스톤은 자동으로 풀립니다.
STATUS_IN_OTHER_TEAM	400	고른 상태가 다른 팀 전용입니다(field: "status_id"). 공용 상태나 이슈 팀의 상태를 고르세요.
STATUS_ARCHIVED	400	고른 상태가 지워진(보관된) 상태입니다(field: "status_id"). GET /api/v1/workflow_states?available_for_team=<team_id> 로 쓸 수 있는 상태를 다시 고르세요.
INVALID_STATUS_MAPPING	400	복원에 실은 status_map 의 상태를 그 팀에서 쓸 수 없거나(다른 팀 전용 · 지워짐 · 이 워크스페이스 밖) 키가 이 워크스페이스의 상태가 아닙니다(field: "status_map" · status_ids). 이슈는 바뀌지 않았습니다. STATUS_MAPPING_REQUIRED 의 candidates 에서 다시 고르세요.
AI_AGENT_REVOKED	400	회수된 AI 에이전트는 담당자로 지정할 수 없습니다.
PRECONDITION_REQUIRED	412	PATCH 본문에 expected_version 이 없습니다. 이슈를 읽고 그 version 을 함께 보내세요.
NOT_FOUND	404	대상이 없거나 이 Key 로 볼 수 없습니다. 둘은 구분하지 않습니다.
VERSION_CONFLICT	409	읽은 뒤 다른 사람이 먼저 고쳤습니다. 다시 읽고 새 version 으로 보내세요.
STATUS_MAPPING_REQUIRED	409	복원하려는 버전의 상태(또는 함께 되돌아가는 하위 이슈의 상태)가 지워졌거나(보관) 결과 팀에서 쓸 수 없습니다. 이슈는 바뀌지 않았습니다. required 에 그 상태(archived: true = 지워짐), candidates 에 고를 수 있는 상태, suggested 에 같은 이름의 제안이 실립니다. 원본 상태마다 하나를 골라 status_map({ 원본 status_id: 대상 status_id })을 실어 다시 보내세요.
NO_TARGET_STATES	422	매핑이 필요한데 결과 팀에서 고를 수 있는 상태가 없습니다. 워크플로 설정에서 상태를 먼저 만드세요.
CONCURRENT_MOVE	409	다른 변경과 동시에 처리되다 겹쳤습니다. 잠시 뒤 같은 요청을 다시 보내세요.
METRIC_ARCHIVED	409	보관된 지표에는 값을 넣을 수 없습니다. 지표 화면에서 보관을 해제하세요.
SYSTEM_METRIC_READONLY	409	시스템이 집계하는 값이라 덮어쓸 수 없습니다.
LOCK_TIMEOUT	503	같은 대상에 대한 작업이 겹쳤습니다. 잠시 뒤 다시 보내세요.
STATEMENT_TIMEOUT	503	조회가 너무 오래 걸려 중단했습니다. 범위(limit·필터)를 줄이세요.

요청 한도 초과(429)

한도를 넘으면 429 를 받습니다. 이 응답에는 위 형식의 code 가 없을 수 있으니 상태 코드로 판단하고, Retry-After 헤더(초)만큼 기다린 뒤 다시 보내세요. 한도는 API Key 에 있습니다.