이 페이지는 기계 번역되었습니다. 잘못된 부분을 발견하셨나요?개선을 도와주세요.
Skip to content

오류 코드 ​

모든 JSON 오류 응답은 같은 형식을 가집니다.

json
{
  "error": "Job not found",
  "code": "NOT_FOUND",
  "requestId": "req-42"
}
필드항상 포함의미
error예사람이 읽을 수 있는 메시지입니다. 사용자에게 그대로 보여 줘도 안전합니다. 파싱하지 마세요.
code예안정적이고 기계가 읽을 수 있는 코드입니다. 이 값으로 분기하세요.
requestId예이 요청에 대한 서버의 ID입니다. 문제를 보고할 때 함께 알려 주세요. 서버 로그와 일치합니다.
details경우에 따라검증 메시지처럼 일부 4xx 오류에 대한 추가 정보입니다.

메시지는 릴리스마다 바뀔 수 있습니다. 코드는 바뀌지 않으므로 클라이언트 로직은 code 기준으로 작성하세요.

HTTP 상태에서 파생되는 코드 ​

라우트가 자체 코드를 지정하지 않으면 서버는 상태에서 코드를 만들어 냅니다.

HTTP 상태code
400BAD_REQUEST
401AUTH_REQUIRED
403FORBIDDEN
404NOT_FOUND
409CONFLICT
413PAYLOAD_TOO_LARGE
415UNSUPPORTED_MEDIA_TYPE
422UNPROCESSABLE_ENTITY
429RATE_LIMITED
500INTERNAL_ERROR
501NOT_IMPLEMENTED
503SERVICE_UNAVAILABLE
507INSUFFICIENT_STORAGE

그 외의 4xx는 BAD_REQUEST로, 그 외의 5xx는 INTERNAL_ERROR로 처리됩니다.

라우트가 더 구체적인 코드를 지정할 수 있으며, 이 경우 응답에는 해당 코드가 대신 포함됩니다. 예를 들어 AI 번들이 없어 실행할 수 없는 도구는 기능별 코드를 반환합니다. 이러한 코드는 해당 코드를 발생시키는 기능과 함께 설명합니다.

인증과 접근 ​

code상태대응 방법
AUTH_REQUIRED401세션 토큰 또는 API 키(si_...)와 함께 Authorization: Bearer <token>를 보내세요.
FORBIDDEN403자격 증명은 유효하지만 권한이 없습니다. 관리자에게 권한을 요청하세요.
MUST_CHANGE_PASSWORD403다른 엔드포인트를 호출하려면 먼저 계정의 비밀번호를 변경해야 합니다. 세션 토큰으로 POST /api/auth/change-password를 호출한 뒤 다시 시도하세요.
USER_DISABLED403계정이 비활성화되어 있습니다. 관리자가 다시 활성화해야 합니다.
LOGIN_THROTTLED429로그인 실패 횟수가 너무 많습니다. 잠시 기다린 후 다시 시도하세요.
VALIDATION_ERROR400요청 본문 또는 매개변수가 검증에 실패했습니다. details에 문제가 표시됩니다.

처음 실행할 때의 관리자 계정은 admin이고 비밀번호는 admin이며, DEFAULT_USERNAME 또는 DEFAULT_PASSWORD가 이를 변경한 경우는 예외입니다. SKIP_MUST_CHANGE_PASSWORD가 설정되어 있지 않으면, 비밀번호를 변경할 때까지 이 계정은 모든 호출에서 MUST_CHANGE_PASSWORD를 받습니다.

작업 ​

실패한 작업은 HTTP 오류가 아니라 작업 자체에 실패 이유를 보고합니다. GET /api/v1/jobs/{jobId}에서 error.code와 error.message를 읽으세요. 진행 상황 추적을 참고하세요.

아직 목록화되지 않은 코드 ​

개별 기능(예: 암호화, OIDC, SCIM, 팀)에서 발생하는 코드는 아직 이 페이지에 설명되어 있지 않습니다. 각 코드는 안정적인 코드입니다. 목록에 없는 코드는 내용을 알 수 없는 값으로 간주하고 상태에 따라 처리하세요.