# 오류 처리

## 통합된 오류 응답 형식

모든 API 오류는 통합된 JSON 형식을 반환합니다.

```json
{
  "code": 2010,
  "message": "Insufficient credits",
  "suggestion": "Please top up your account at https://platform.tripo3d.ai",
  "request_id": "req_abc123"
}
```

| 필드 | 유형 | 설명 |
| :-: | :-: | :-: |
| code | 정수 | 오류 코드 |
| message | 문자열 | 오류 설명 |
| suggestion | 문자열 | 제안된 수정 사항 |
| request_id | 문자열 | 문제 해결을 위한 고유 요청 식별자 |

## HTTP 상태 코드

| 상태 코드 | 의미 | 설명 |
| :-: | :-: | :-: |
| 200 | 성공 | 요청이 성공적으로 처리되었습니다. |
| 400 | 잘못된 매개변수 | 필수 매개변수가 누락되었거나 형식이 잘못되었습니다. |
| 401 | 인증되지 않음 | API Key가 누락되었거나 유효하지 않습니다. |
| 403 | 권한이 부족합니다. | 리소스에 액세스할 수 있는 권한이 없거나 크레딧이 부족합니다. |
| 404 | 리소스를 찾을 수 없습니다. | 요청한 작업이나 리소스가 존재하지 않습니다. |
| 429 | 요청이 너무 많습니다. | 비율 제한을 초과했습니다. 요청 빈도를 줄이세요 |
| 500 | 서비스 오류 | 내부 서버 오류입니다. 나중에 다시 시도해 보세요 |

## 오류 코드 참조

| 오류 코드 | 의미 | 권장 취급 |
| :-: | :-: | :-: |
| 1000 | 잘못된 API Key | API Key가 올바른지 또는 삭제되었는지 확인하세요. |
| 1001 | 승인되지 않은 | 요청 헤더에 `Authorization`가 포함되어 있는지 확인하세요. |
| 2000 | 비율 제한을 초과했습니다. | 요청 빈도를 줄이고 지수 백오프로 재시도 구현 |
| 2002 | 지원되지 않는 요청 매개변수 | 요청 본문 필드 이름과 값이 문서와 일치하는지 확인하세요. |
| 2003 | 빈 입력 파일 | 업로드된 파일이 비어 있지 않고 유효한 형식을 사용하는지 확인하세요. |
| 2004 | 지원되지 않는 파일 형식 | 파일 형식이 지원되는 목록에 있는지 확인하세요. |
| 2008 | 콘텐츠 정책 위반 | 금지된 단어나 이미지가 포함되지 않도록 입력 내용을 수정하세요. |
| 2010 | 크레딧이 부족합니다. | 콘솔에서 크레딧을 충전하세요 |
| 2015 | 더 이상 사용되지 않는 버전 | 최신 API 버전으로 업그레이드 |
| 2018 | 모델이 너무 복잡함 | 입력 모델의 복잡성이나 폴리카운트를 줄입니다. |

## 오류 처리 예

### Python

```python
import time
import requests

def call_api_with_retry(url, headers, payload=None, max_retries=3):
    for attempt in range(max_retries):
        if payload:
            response = requests.post(url, headers=headers, json=payload)
        else:
            response = requests.get(url, headers=headers)

        if response.status_code == 200:
            return response.json()

        if response.status_code == 429:
            wait = 2 ** attempt
            print(f"Rate limit triggered. Retrying in {wait} seconds...")
            time.sleep(wait)
            continue

        error = response.json()
        raise Exception(
            f"API error [{error['code']}]: {error['message']} "
            f"(suggestion: {error.get('suggestion', 'none')})"
        )

    raise Exception("Maximum retry attempts exhausted")
```

### JavaScript

```javascript
async function callApiWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.ok) {
      return await response.json();
    }

    if (response.status === 429) {
      const wait = 2 ** attempt * 1000;
      console.log(`Rate limit triggered. Retrying in ${wait / 1000} seconds...`);
      await new Promise(resolve => setTimeout(resolve, wait));
      continue;
    }

    const error = await response.json();
    throw new Error(
      `API error [${error.code}]: ${error.message} (suggestion: ${error.suggestion || "none"})`
    );
  }

  throw new Error("Maximum retry attempts exhausted");
}
```

## 재시도 전략 권장 사항

429 비율 제한 및 500 서비스 오류와 같은 재시도 가능한 오류의 경우 지수 백오프 전략을 사용합니다.

1. 첫 번째 재시도: 1초 동안 기다립니다.
2. 두 번째 재시도: 2초 동안 기다립니다.
3. 세 번째 재시도: 4초 동안 기다립니다.
4. 최대 재시도 횟수를 5회 이하로 유지하세요.

400, 401, 403 등 재시도할 수 없는 오류의 경우 직접 예외를 발생시키고 근본적인 문제를 해결하세요.