오류 처리

통합된 오류 응답 형식

모든 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	모델이 너무 복잡함	입력 모델의 복잡성이나 폴리카운트를 줄입니다.

오류 처리 예

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")

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초 동안 기다립니다.
두 번째 재시도: 2초 동안 기다립니다.
세 번째 재시도: 4초 동안 기다립니다.
최대 재시도 횟수를 5회 이하로 유지하세요.

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