콘텐츠로 이동

오류 및 재시도

비즈니스 오류는 응답 본문의 최상위 수준에서 code 및 message를 반환합니다. detail는 일반적으로 message와 동일하지만 아래와 같이 더 짧은 다른 설명일 수도 있습니다; 사용자에게는 message를 표시하십시오. 메시지는 중국어로 제공됩니다:

{
"code": "CONCURRENCY_LIMITED",
"message": "排队中的文件已达上限(1000 个),请等部分文件翻译完成后再提交",
"detail": "排队文件完成一部分后可继续提交"
}

일부 비즈니스 오류는 code만 반환합니다. 유효성 검사 실패 시에는 detail에 필드 오류 목록과 함께 422이 반환됩니다:

{
"detail": [
{ "loc": ["body", "target_lang"], "msg": "Field required", "type": "missing" }
]
}

오류는 먼저 HTTP 상태로 처리한 다음 code로 처리하십시오. 많은 오류는 일반적인 UNKNOWN_ERROR만 반환하며, 특정 code을 포함하는 경우는 일부에 불과합니다(예: 아래의 429 사례). 문제 해결을 위해 X-Request-Id 응답 헤더를 기록하십시오.

상태의미조언
400잘못된 요청입니다. 예를 들어, 선택한 설정을 사용할 수 없습니다.요청을 수정하십시오; 재시도하지 마십시오.
401자격 증명이 누락되었거나, 유효하지 않거나, 만료되었거나, 취소되었습니다.자격 증명 변경
402잔액(부채 차감 후)이 작업 임계값을 초과하지 않거나 음수인 경우, API 키의 남은 예산이 너무 적을 수 있습니다.잔액을 충전하거나(또는 키의 예산을 증액한 후) 다시 제출하세요.
403키의 제한으로 인해 이 작업을 수행할 수 없거나(예: 변환 설정이 허용되지 않는 경우), 계정이 비활성화되었거나, 서명된 브라우저에서만 수행해야 하는 작업(예: API 키 관리)입니다.키 설정을 확인하거나 웹사이트를 사용하십시오.
404해당 리소스가 존재하지 않거나 삭제되었거나 다른 계정에 속해 있습니다(세 가지 모두 동일하게 표시됨).ID 확인
409멱등 키가 다른 요청에 사용되었거나, 해당 리소스의 상태가 작업을 허용하지 않습니다.원래 연산을 조회한 다음 결정합니다.
410리소스 또는 엔드포인트가 영구적으로 사라졌습니다. 예를 들어, 폐기된 엔드포인트나 idempotency 키에 연결된 삭제된 작업이 있습니다.재시도하지 마십시오.
413파일 또는 요청 본문이 제한 크기를 초과합니다.파일 크기를 줄이세요
415지원되지 않는 파일 형식다른 형식을 사용하십시오.
422검증에 실패했거나 파일이 비어 있거나 처리할 내용이 없습니다.필드를 수정하십시오; 자동으로 재시도하지 마십시오.
429레이트, 대기열 크기 또는 예산 제한아래를 참조하십시오.
5xx임시 서비스 오류최대 시도 횟수를 설정한 지수 백오프
code의미해야 할 일
RATE_LIMITED요청이 너무 많습니다Retry-After을 기다린 후 다시 시도하십시오.
CONCURRENCY_LIMITED파일 번역 작업이 너무 많이 대기 중입니다.Retry-After이 발생할 때까지 기다리거나, 일부 작업이 완료될 때까지 기다립니다.
AUTH_API_KEY_QUOTA_EXCEEDED키의 예산이 소진되었습니다.예산이 증액될 때까지 재시도하지 마십시오.

Retry-After가 없는 429은 지수적 백오프로 처리해야 합니다.

  • 쿼리들은 직접 재시도할 수 있습니다.
  • 작성 요청을 재시도할 때는 동일한 Idempotency-Key과 정확히 동일한 본문을 재사용하고, 각 새로운 제출에는 새 키를 사용하십시오.
  • 업로드 실패 시 새 업로드 주소를 요청하십시오.
  • 각 요청에 대해 연결, 읽기 및 전체 시간 초과 값을 설정하고, 재시도 시 무작위 지터를 추가하며, 시도 횟수를 제한합니다.
import random
import time
for attempt in range(5):
response = call_api()
if response.status_code not in {429, 500, 502, 503, 504}:
break
if response.status_code == 429 and response.json().get("code") == "AUTH_API_KEY_QUOTA_EXCEEDED":
break
retry_after = response.headers.get("Retry-After")
delay = float(retry_after) if retry_after else min(2 ** attempt, 16)
time.sleep(delay + random.random())