> ## Documentation Index
> Fetch the complete documentation index at: https://ai-kb.automationanywhere.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 일반 API 오류

> API 오류에 대한 문제 해결 조언

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

## 오류 응답 형식

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

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

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

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

## HTTP 상태 코드

### 400 잘못된 요청

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

<AccordionGroup>
  <Accordion title="VALIDATION_ERROR">
    **오류 코드**: `VALIDATION_ERROR`
    **상태 코드**: `400`

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

    **일반적인 원인**:

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

    **예시 응답**:

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

    **문제 해결**:

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

  <Accordion title="INVALID_API_KEY">
    **오류 코드**: `INVALID_API_KEY`
    **상태 코드**: `400`

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

    **문제 해결**:

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

  <Accordion title="INVALID_CREDENTIALS">
    **오류 코드**: `INVALID_CREDENTIALS`
    **상태 코드**: `400`

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

    **문제 해결**:

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

  <Accordion title="INVALID_OR_EXPIRED_JWT_TOKEN">
    **오류 코드**: `INVALID_OR_EXPIRED_JWT_TOKEN`
    **상태 코드**: `400`

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

    **문제 해결**:

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

### 401 인증되지 않음

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

<AccordionGroup>
  <Accordion title="AUTHENTICATION">
    **오류 코드**: `AUTHENTICATION`
    **상태 코드**: `401`

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

    **문제 해결**:

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

  <Accordion title="INVALID_BEARER_TOKEN">
    **오류 코드**: `INVALID_BEARER_TOKEN`
    **상태 코드**: `401`

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

    **문제 해결**:

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

  <Accordion title="EMAIL_IS_NOT_VERIFIED">
    **오류 코드**: `EMAIL_IS_NOT_VERIFIED`
    **상태 코드**: `401`

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

    **문제 해결**:

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

### 403 접근 거부됨

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

<AccordionGroup>
  <Accordion title="AUTHORIZATION">
    **오류 코드**: `AUTHORIZATION`
    **상태 코드**: `403`

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

    **문제 해결**:

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

  <Accordion title="PERMISSION_DENIED">
    **오류 코드**: `PERMISSION_DENIED`
    **상태 코드**: `403`

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

    **문제 해결**:

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

  <Accordion title="DOMAIN_NOT_ALLOWED">
    **오류 코드**: `DOMAIN_NOT_ALLOWED`
    **상태 코드**: `403`

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

    **문제 해결**:

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

### 404 찾을 수 없음

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

<AccordionGroup>
  <Accordion title="ENTITY_NOT_FOUND">
    **오류 코드**: `ENTITY_NOT_FOUND`
    **상태 코드**: `404`

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

    **일반적인 시나리오**:

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

    **문제 해결**:

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

  <Accordion title="FILE_NOT_FOUND">
    **오류 코드**: `FILE_NOT_FOUND`
    **상태 코드**: `404`

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

    **문제 해결**:

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

  <Accordion title="FLOW_NOT_FOUND">
    **오류 코드**: `FLOW_NOT_FOUND`
    **상태 코드**: `404`

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

    **문제 해결**:

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

  <Accordion title="CONFIG_NOT_FOUND">
    **오류 코드**: `CONFIG_NOT_FOUND`
    **상태 코드**: `404`

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

    **문제 해결**:

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

### 500 내부 서버 오류

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

<AccordionGroup>
  <Accordion title="ENGINE_OPERATION_FAILURE">
    **오류 코드**: `ENGINE_OPERATION_FAILURE`
    **상태 코드**: `500`

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

    **문제 해결**:

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

  <Accordion title="EXTERNAL_SERVICE">
    **오류 코드**: `EXTERNAL_SERVICE`
    **상태 코드**: `500`

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

    **일반적인 시나리오**:

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

    **문제 해결**:

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

  <Accordion title="INFRASTRUCTURE">
    **오류 코드**: `INFRASTRUCTURE`
    **상태 코드**: `500`

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

    **문제 해결**:

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

  <Accordion title="OPEN_AI_FAILED">
    **오류 코드**: `OPEN_AI_FAILED`
    **상태 코드**: `500`

    **설명**: OpenAI API 호출 실패.

    **문제 해결**:

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

### 503 서비스 사용 불가

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

<AccordionGroup>
  <Accordion title="EXECUTION_TIMEOUT">
    **오류 코드**: `EXECUTION_TIMEOUT`
    **상태 코드**: `503`

    **설명**: 작업 시간 초과.

    **문제 해결**:

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

## 비즈니스 로직 오류

<AccordionGroup>
  <Accordion title="QUOTA_EXCEEDED">
    **오류 코드**: `QUOTA_EXCEEDED`
    **상태 코드**: `400` 또는 `429`

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

    **문제 해결**:

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

  <Accordion title="FEATURE_DISABLED">
    **오류 코드**: `FEATURE_DISABLED`
    **상태 코드**: `400`

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

    **문제 해결**:

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

  <Accordion title="FLOW_IN_USE">
    **오류 코드**: `FLOW_IN_USE`
    **상태 코드**: `400`

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

    **문제 해결**:

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

  <Accordion title="EXISTING_USER">
    **오류 코드**: `EXISTING_USER`
    **상태 코드**: `400`

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

    **문제 해결**:

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

## 통합 관련 오류

<AccordionGroup>
  <Accordion title="INVALID_APP_CONNECTION">
    **오류 코드**: `INVALID_APP_CONNECTION`
    **상태 코드**: `400`

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

    **문제 해결**:

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

  <Accordion title="INVALID_SAML_RESPONSE">
    **오류 코드**: `INVALID_SAML_RESPONSE`
    **상태 코드**: `400`

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

    **문제 해결**:

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

  <Accordion title="RATE_LIMITED">
    **오류 코드**: `RATE_LIMITED` 또는 `ratelimited`
    **상태 코드**: `429`

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

    **문제 해결**:

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

## 도움 받기

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

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