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