메인 콘텐츠로 건너뛰기
BetterToken API 오류는 HTTP 상태와 응답 본문을 함께 보고 진단하세요. error.message의 요청 ID를 기록하고, 인증이나 설정 오류를 수정한 뒤 다시 보내세요. 일시적인 장애로 확인된 경우에만 재시도하세요.

문제 해결 전 준비

Model ID, Base URL, 실패한 응답을 준비하세요. BetterToken Dashboard에서 Key 상태와 현재 잔액을 확인하세요. 아직 모델 요청을 성공시키지 못했다면 SDK 예제 또는 도구 설정 가이드부터 시작하세요.

오류 응답 읽기

BetterToken은 API 오류를 JSON 형태로 반환합니다. 예를 들어 Key 없는 요청은 다음 응답을 반환할 수 있습니다.
error.code가 비어 있어도 error.message를 읽으세요. 메시지의 요청 ID로 실패한 시도를 식별할 수 있습니다. Key 없이 /v1/models에 요청하면 401이 반환됩니다. 이 요청으로는 모델의 응답 생성 여부를 확인할 수 없습니다. 지원팀에 문의하기 전에 다음 정보를 기록하세요. 스크린샷, 지원 문의, 공유 로그에 BetterToken API Key를 포함하지 마세요.

HTTP 상태 확인하기

아래 표는 일반적인 HTTP/API 의미와 연결된 설정 안내를 기준으로 합니다. BetterToken 고유 오류 코드 목록은 아니므로 실제 응답을 읽고 해결 방법을 선택하세요. 프로토콜과 경로 접미사 오류는 Base URL FAQ를, 캐시 관련 질문은 캐시 과금 FAQ를 참고하세요.

일시적인 장애 재시도하기

일시적인 429 또는 서버 장애로 확인되면 무작위 지연을 더한 지수 백오프를 상한 내에서 사용하세요. Retry-After가 반환되면 따르되 재시도 대기 한도를 넘으면 루프를 중단하고 밖에서 기다리세요. SDK 재시도와 직접 구현한 루프의 시도 횟수는 합산되므로 직접 정책을 구현할 때는 SDK 재시도를 끄세요. 원인을 수정하지 않은 400, 401, 403, 잔액 또는 설정 오류는 재시도하지 마세요. 클라이언트 타임아웃이나 스트림 중단이 처리 전에 실패했음을 의미하지는 않습니다. 특히 이미지 생성이나 작업이 중복될 수 있는 워크플로는 먼저 Dashboard를 확인하세요. 아래 예제는 비스트리밍 Chat Completions 요청을 최대 네 번 시도합니다. HTTP 500, 502, 503을 재시도합니다. 429는 응답이 일시적인 요청 속도 제한임을 확인할 때까지 재시도하지 않습니다. 타임아웃, 네트워크 예외, 504에서는 중단하여 완료 여부를 확인할 수 있게 합니다. 시도당 재시도 대기는 최대 30초입니다.

요청 준비하기

모델 광장에서 현재 Model ID를 복사하고 두 자리표시자를 모두 바꾸세요. Chat Completions에서 사용 가능한 텍스트 모델을 선택하세요.
Python 예제는 표준 라이브러리를 사용합니다. JavaScript 예제는 .mjs 파일로 저장하고 fetch와 AbortSignal.timeout을 제공하는 Node.js 버전으로 실행하세요.
응답 본문에 지속적인 설정, 잔액, 접근 문제가 나타나면 상태 코드만으로 재시도가 가능해 보여도 루프를 중단하고 수정하세요. 이 짧은 텍스트 예제를 다른 작업에 적용하기 전에 앱에 맞는 완료 확인을 추가하세요.

증상에 맞는 가이드 찾기

해결 여부 확인하기

실패했던 클라이언트, Base URL, Model ID를 그대로 사용해 중요한 작업에 영향을 주지 않는 짧은 요청을 한 번 보내세요. 정상 응답을 확인하고 Dashboard에서 해당 기록을 찾으세요. 모델, 상태, 토큰 사용량, 요금을 확인한 뒤 더 큰 워크플로를 재개하세요.

자주 묻는 질문

429가 반환되면 항상 기다렸다가 재시도해야 하나요?

사용량 제한 진단 FAQ를 보고 확인할 사항과 해당 응답에 재시도가 적절한지 판단하세요.

한 번 실패하면 타임아웃을 늘려야 하나요?

먼저 클라이언트, 프록시, 업스트림 요청 중 어디서 대기를 중단했는지 확인하세요. 타임아웃 설정 안내를 적용한 뒤 작은 요청으로 검증하세요.

관련 가이드