메인 콘텐츠로 건너뛰기

일반 API 오류

이 문서는 EKB 클라우드 플랫폼을 사용할 때 가장 흔히 encounter할 수 있는 API 오류를 이해하는 데 도움이 됩니다. 다양한 HTTP 상태 코드 및 특정 오류 코드에 대한 세부 사항을 제공하여 이러한 문제를 효과적으로 해결하는 데 필요한 문제 해결 단계를 안내합니다. 오류 응답 형식과 API 사용과 관련된 일반적인 함정을 이해하면 오류를 더 잘 처리하고 개발 경험을 향상시킬 수 있습니다.

오류 응답 형식​

모든 API 오류는 일관된 형식을 따릅니다:

{
  "status_code": 400,
  "error": {
    "code": "ERROR_CODE",
    "message": "사람이 읽을 수 있는 오류 메시지"
  },
  "detail": "추가 오류 세부 사항(선택 사항)"
}

일부 오류에는 다음도 포함될 수 있습니다:

  • error_id: 오류 추적을 위한 고유 식별자
  • invalid_fields: 유효성 검사에 실패한 필드 목록(유효성 검사 오류의 경우)

HTTP 상태 코드​

400 잘못된 요청​

잘못된 입력이나 형식이 잘못된 요청으로 인한 클라이언트 측 오류.

VALIDATION_ERROR

오류 코드: VALIDATION_ERROR 상태 코드: 400

설명: 요청 유효성 검사 실패. 요청의 하나 이상의 필드가 유효하지 않습니다.

일반적인 원인:

  • 필수 필드 누락
  • 잘못된 필드 형식(예: 잘못된 이메일, 날짜 형식)
  • 허용 범위를 벗어난 필드 값
  • 잘못된 데이터 유형

예시 응답:

{
  "status_code": 400,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "잘못된 입력 데이터",
    "invalid_fields": ["email", "project_id"]
  }
}

문제 해결:

  1. invalid_fields 배열을 검토하여 문제가 있는 필드를 식별합니다
  2. API 문서에서 필드 요구 사항을 확인합니다
  3. 데이터 유형이 예상 형식과 일치하는지 확인합니다
  4. 모든 필수 필드가 제공되었는지 확인합니다
INVALID_API_KEY

오류 코드: INVALID_API_KEY 상태 코드: 400

설명: 제공된 API 키가 유효하지 않거나 형식이 잘못되었습니다.

문제 해결:

  1. API 키가 올바르게 복사되었는지 확인합니다(추가 공백 없음)
  2. 내 계정 > API 키에서 API 키가 활성화되어 있는지 확인합니다
  3. 환경에 맞는 올바른 API 키를 사용하고 있는지 확인합니다
  4. 필요한 경우 API 키를 다시 생성합니다
INVALID_CREDENTIALS

오류 코드: INVALID_CREDENTIALS 상태 코드: 400

설명: 인증 자격 증명이 유효하지 않습니다.

문제 해결:

  1. 이메일과 비밀번호가 올바른지 확인합니다
  2. 계정이 잠겼거나 비활성화되어 있는지 확인합니다
  3. 비밀번호를 재설정해 보세요
  4. 올바른 인증 방법을 사용하고 있는지 확인합니다
INVALID_OR_EXPIRED_JWT_TOKEN

오류 코드: INVALID_OR_EXPIRED_JWT_TOKEN 상태 코드: 400

설명: JWT 토큰이 유효하지 않거나, 만료되었거나, 형식이 잘못되었습니다.

문제 해결:

  1. 인증 토큰을 새로고침합니다
  2. 로그아웃 후 다시 로그인합니다
  3. 토큰 만료 시간을 확인합니다
  4. 토큰이 올바른 헤더 형식으로 전송되고 있는지 확인합니다

401 인증되지 않음​

인증이 필요하거나 인증에 실패했습니다.

AUTHENTICATION

오류 코드: AUTHENTICATION 상태 코드: 401

설명: 이 리소스에 접근하려면 인증이 필요합니다.

문제 해결:

  1. 로그인되어 있는지 확인합니다
  2. 세션이 만료되었는지 확인합니다
  3. 요청에 인증 헤더가 포함되어 있는지 확인합니다
  4. 필요한 경우 다시 인증합니다
INVALID_BEARER_TOKEN

오류 코드: INVALID_BEARER_TOKEN 상태 코드: 401

설명: 제공된 Bearer 토큰이 유효하지 않습니다.

문제 해결:

  1. 토큰 형식을 확인합니다: Bearer <token>
  2. 토큰이 만료되었는지 확인합니다
  3. 인증 토큰을 다시 생성합니다
  4. 토큰이 취소되지 않았는지 확인합니다
EMAIL_IS_NOT_VERIFIED

오류 코드: EMAIL_IS_NOT_VERIFIED 상태 코드: 401

설명: 이메일 주소가 확인되지 않았습니다.

문제 해결:

  1. 이메일에서 확인 링크를 확인합니다
  2. 새 확인 이메일을 요청합니다
  3. 이메일 주소가 올바른지 확인합니다
  4. 스팸/정크 폴더를 확인합니다

403 접근 거부됨​

권한이 부족하여 접근이 거부되었습니다.

AUTHORIZATION

오류 코드: AUTHORIZATION 상태 코드: 403

설명: 이 작업을 수행할 권한이 없습니다.

문제 해결:

  1. 필요한 역할/권한이 있는지 확인합니다
  2. 프로젝트/팀의 구성원인지 확인합니다
  3. 프로젝트/팀 관리자에게 접근을 부여하도록 요청합니다
  4. 올바른 리소스에 접근하고 있는지 확인합니다
PERMISSION_DENIED

오류 코드: PERMISSION_DENIED 상태 코드: 403

설명: 요청된 작업에 대한 권한이 거부되었습니다.

문제 해결:

  1. 사용자 역할과 권한을 검토합니다
  2. 프로젝트/팀 접근 설정을 확인합니다
  3. 리소스 소유권을 확인합니다
  4. 접근을 위해 관리자에게 문의합니다
DOMAIN_NOT_ALLOWED

오류 코드: DOMAIN_NOT_ALLOWED 상태 코드: 403

설명: 귀하의 이메일 도메인이 이 작업에 허용되지 않습니다.

문제 해결:

  1. 이메일 도메인이 허용 목록에 있는지 확인합니다
  2. 도메인을 추가하도록 관리자에게 문의합니다
  3. 허용된 이메일 주소를 사용합니다

404 찾을 수 없음​

요청된 리소스가 존재하지 않습니다.

ENTITY_NOT_FOUND

오류 코드: ENTITY_NOT_FOUND 상태 코드: 404

설명: 요청된 리소스를 찾을 수 없습니다.

일반적인 시나리오:

  • 프로젝트를 찾을 수 없음
  • 에이전트를 찾을 수 없음
  • 문서를 찾을 수 없음
  • 사용자를 찾을 수 없음

문제 해결:

  1. 리소스 ID가 올바른지 확인합니다
  2. 리소스가 삭제되었는지 확인합니다
  3. 리소스에 접근할 수 있는지 확인합니다
  4. 올바른 프로젝트/워크스페이스를 사용하고 있는지 확인합니다
FILE_NOT_FOUND

오류 코드: FILE_NOT_FOUND 상태 코드: 404

설명: 요청된 파일이 존재하지 않습니다.

문제 해결:

  1. 파일 ID 또는 경로가 올바른지 확인합니다
  2. 파일이 삭제되었는지 확인합니다
  3. 파일이 예상 위치에 있는지 확인합니다
  4. 파일 권한을 확인합니다
FLOW_NOT_FOUND

오류 코드: FLOW_NOT_FOUND 상태 코드: 404

설명: 요청된 워크플로우/플로우를 찾을 수 없습니다.

문제 해결:

  1. 플로우 ID가 올바른지 확인합니다
  2. 플로우가 삭제되었는지 확인합니다
  3. 플로우에 접근할 수 있는지 확인합니다
  4. 플로우가 현재 프로젝트에 존재하는지 확인합니다
CONFIG_NOT_FOUND

오류 코드: CONFIG_NOT_FOUND 상태 코드: 404

설명: 필요한 구성을 찾을 수 없습니다.

문제 해결:

  1. 구성이 존재하는지 확인합니다
  2. 설정에서 구성을 확인합니다
  3. 필요한 서비스가 구성되어 있는지 확인합니다
  4. 구성을 검토합니다

500 내부 서버 오류​

조사가 필요한 서버 측 오류.

ENGINE_OPERATION_FAILURE

오류 코드: ENGINE_OPERATION_FAILURE 상태 코드: 500

설명: 내부 엔진 작업이 실패했습니다.

문제 해결:

  1. 잠시 후 요청을 다시 시도합니다
  2. status.getodin.ai에서 시스템 상태를 확인합니다
  3. 지속되면 오류 세부 사항과 함께 지원팀에 문의합니다
  4. 사용 가능한 경우 오류 ID를 제공합니다
EXTERNAL_SERVICE

오류 코드: EXTERNAL_SERVICE 상태 코드: 500

설명: 이 작업에 필요한 외부 서비스가 실패했습니다.

일반적인 시나리오:

  • LLM 제공업체 API 실패
  • 서드파티 통합 실패(Google Drive, Slack 등)
  • 외부 API 시간 초과

문제 해결:

  1. 외부 서비스 상태를 확인합니다
  2. 외부 서비스의 API 키/자격 증명을 확인합니다
  3. 요청을 다시 시도합니다
  4. 통합 구성을 확인합니다
  5. 문제가 지속되면 지원팀에 문의합니다
INFRASTRUCTURE

오류 코드: INFRASTRUCTURE 상태 코드: 500

설명: 인프라 오류(데이터베이스, 스토리지 등).

문제 해결:

  1. 요청을 다시 시도합니다
  2. 시스템 상태를 확인합니다
  3. 지속되면 지원팀에 문의합니다
  4. 오류 세부 사항과 타임스탬프를 제공합니다
OPEN_AI_FAILED

오류 코드: OPEN_AI_FAILED 상태 코드: 500

설명: OpenAI API 호출 실패.

문제 해결:

  1. OpenAI 서비스 상태를 확인합니다
  2. API 키가 유효하고 크레딧이 있는지 확인합니다
  3. 속도 제한을 확인합니다
  4. 지수적 백오프로 다시 시도합니다
  5. 모델 가용성을 확인합니다

503 서비스 사용 불가​

서비스를 일시적으로 사용할 수 없습니다.

EXECUTION_TIMEOUT

오류 코드: EXECUTION_TIMEOUT 상태 코드: 503

설명: 작업 시간 초과.

문제 해결:

  1. 요청을 다시 시도합니다
  2. 가능한 경우 작업을 단순화합니다
  3. 시스템이 높은 부하에 걸려 있는지 확인합니다
  4. 큰 작업을 더 작은 작업으로 나눕니다
  5. 시간 초과가 지속되면 지원팀에 문의합니다

비즈니스 로직 오류​

QUOTA_EXCEEDED

오류 코드: QUOTA_EXCEEDED 상태 코드: 400 또는 429

설명: 할당량 한도를 초과했습니다.

문제 해결:

  1. 내 계정 > 대시보드에서 현재 사용량을 확인합니다
  2. 구독 제한을 검토합니다
  3. 필요한 경우 플랜을 업그레이드합니다
  4. 할당량 재설정 기간을 기다립니다
  5. 할당량 증가를 위해 영업팀에 문의합니다
FEATURE_DISABLED

오류 코드: FEATURE_DISABLED 상태 코드: 400

설명: 이 기능은 귀하의 계정에서 비활성화되어 있습니다.

문제 해결:

  1. 구독 플랜을 확인합니다
  2. 기능 가용성을 확인합니다
  3. 기능이 더 높은 티어를 요구하는 경우 플랜을 업그레이드합니다
  4. 기능 접근을 위해 지원팀에 문의합니다
FLOW_IN_USE

오류 코드: FLOW_IN_USE 상태 코드: 400

설명: 워크플로우가 현재 사용 중이어 수정할 수 없습니다.

문제 해결:

  1. 활성 실행이 완료될 때까지 기다립니다
  2. 활성 워크플로우 실행을 취소합니다
  3. 워크플로우 실행 상태를 확인합니다
  4. 실행이 완료된 후 다시 시도합니다
EXISTING_USER

오류 코드: EXISTING_USER 상태 코드: 400

설명: 이 이메일을 가진 사용자가 이미 존재합니다.

문제 해결:

  1. 대신 로그인을 시도합니다
  2. 자격 증명을 잊은 경우 비밀번호 재설정을 사용합니다
  3. 다른 이메일 주소를 사용합니다
  4. 계정 복구가 필요한 경우 지원팀에 문의합니다

통합 관련 오류​

INVALID_APP_CONNECTION

오류 코드: INVALID_APP_CONNECTION 상태 코드: 400

설명: 유효하지 않거나 만료된 앱 연결(OAuth 통합).

문제 해결:

  1. 통합을 다시 인증합니다
  2. OAuth 토큰 만료를 확인합니다
  3. 통합 자격 증명을 확인합니다
  4. 설정에서 통합을 다시 연결합니다
INVALID_SAML_RESPONSE

오류 코드: INVALID_SAML_RESPONSE 상태 코드: 400

설명: SSO 제공자로부터 유효하지 않은 SAML 응답.

문제 해결:

  1. SSO 구성을 확인합니다
  2. SAML 메타데이터 URL을 확인합니다
  3. SSO 제공자가 접근 가능한지 확인합니다
  4. SSO 구성 검토를 위해 지원팀에 문의합니다
RATE_LIMITED

오류 코드: RATE_LIMITED 또는 ratelimited 상태 코드: 429

설명: API 속도 제한을 초과했습니다.

문제 해결:

  1. 속도 제한 윈도우가 재설정될 때까지 기다립니다
  2. 지수적 백오프를 구현합니다
  3. 요청 빈도를 줄입니다
  4. 응답에서 속도 제한 헤더를 확인합니다
  5. 더 높은 속도 제한을 위해 플랜을 업그레이드합니다

도움 받기​

여기에 나열되지 않은 오류가 발생하거나 도움이 필요한 경우:

  1. 오류 세부 사항 확인: 오류 코드, 메시지 및 error_id를 기록합니다
  2. 시스템 상태 확인: 알려진 문제는 status.getodin.ai를 방문합니다
  3. 문서 검토: 관련 API 문서를 확인합니다
  4. 지원팀에 문의: 다음을 포함하여 지원팀에 이메일을 보냅니다:
    • 오류 코드 및 메시지
    • 오류 ID(사용 가능한 경우)
    • 재현 단계
    • 요청/응답 세부 사항(비식별화)
    • 오류 발생 시각