오류 및 상태 코드
API 문제 응답을 해석하고 실패한 요청을 복구하는 방법, HTTP 오류와 번역 작업 실패를 구분하는 방법을 알아보세요.
성공 응답을 디코딩하기 전에 HTTP 상태를 확인하세요. https://api.lingo.dev/v2의 API는 실패 정보를 JSON 형식의 문제 세부 정보로 반환합니다. 작업 조회에 성공했더라도 실제 작업은 실패했을 수 있으므로 작업 상태도 확인하세요.
문제 응답 읽기 #
문제 응답은 Content-Type: application/problem+json을 사용합니다. 공통 필드는 type, title, status, detail입니다. 이름이 지정된 문제에는 영향을 받는 리소스나 해결 방법을 식별하는 필드도 포함됩니다.
다음은 현지화 작업을 찾을 수 없을 때의 응답 예시입니다.
{
"type": "https://lingo.dev/docs/api/errors/localization-job-not-found",
"title": "Localization job not found",
"status": 404,
"detail": "Localization job lfr_example not found.",
"id": "lfr_example"
}type URI는 문제를 식별합니다. 이름이 지정된 각 문제의 필드와 엔드포인트는 API 오류 목록에서 확인하세요. 오류를 저장하거나 분류할 때는 반환된 URI를 그대로 유지하세요.
잘못된 요청 수정하기 #
요청이 유효성 검사를 통과하지 못하면 type: "about:blank"과 함께 400 잘못된 요청이 반환됩니다. 유효성 검사 세부 정보가 제공되는 경우, errors에 각 문제의 path 및 message가 나열됩니다.
{
"type": "about:blank",
"title": "Bad Request",
"status": 400,
"detail": "Request validation failed",
"errors": [
{
"path": ["payload", "documents", 0, "source"],
"message": "Expected a JSON object"
}
]
}경로는 payload처럼 요청에서 유효성 검사를 수행하는 부분으로 시작하며, 그 뒤에 속성 이름과 0부터 시작하는 배열 인덱스가 이어집니다. 이 예시는 요청 본문의 첫 번째 documents 항목에 있는 source을 가리킵니다. 다시 제출하기 전에 표시된 값을 엔드포인트의 스키마에 맞게 수정하세요. about:blank은 일반적인 문제 유형이므로 이름이 지정된 오류 목록에는 별도 항목이 없습니다.
복구 방법 선택하기 #
| HTTP 상태 | 일반적인 원인 | 다음 조치 |
|---|---|---|
| 400 | 요청이 라우트의 스키마와 일치하지 않습니다. | 반환된 유효성 검사 세부 정보를 참고해 경로, 쿼리, 헤더 또는 본문을 수정하세요. |
| 401 | 인증 정보가 없거나 유효하지 않거나 만료되었습니다. | 사용하려는 키를 불러오거나 사용자 세션을 갱신하세요. |
| 402 | 크레딧이 부족하거나, 요금제에서 해당 기능을 사용할 수 없거나, 역할 기반 접근 제어 권한이 축소된 후 서비스 키가 비활성화되었습니다. | 명시된 조건을 확인하고 계정 또는 요금제 요구 사항을 충족하세요. |
| 403 | 권한이나 필수 사용자 신원 정보가 없거나 기능 플래그 제한이 적용되었습니다. | 호출 주체와 해당 작업의 접근 요구 사항을 확인하세요. |
| 404 | 리소스가 존재하지 않거나 호출 주체에게 표시되지 않습니다. | 식별자, 조직, 리소스 권한을 확인하세요. |
| 409 | 해당 작업이 리소스의 현재 상태와 충돌합니다. | 리소스의 현재 상태를 조회하세요. 안내에 따라 누락된 산출물을 업로드하거나, 실행 중인 작업을 완료하거나, 종료된 검토를 새로 고치세요. |
| 413 | 업로드 또는 요청 본문이 크기 제한을 초과합니다. | 입력 크기를 줄이거나 작업을 나누세요. 산출물은 각각 최대 25 MiB까지 업로드할 수 있습니다. |
| 422 | 요청의 구조는 유효하지만 해당 작업의 제약 조건을 위반합니다. | 유효하지 않은 검토 수정이나 멱등성 키 재사용 등 명시된 문제를 해결하세요. |
| 429 | 사용량 또는 작업 한도에 도달했습니다. | 문제 응답에 재시도 시간이 명시되어 있으면 그에 따르세요. 명시되어 있지 않으면 다시 시도하기 전에 계정 한도를 확인하세요. |
| 5xx | 서버 또는 종속 서비스가 요청을 완료하지 못했습니다. | 리소스 식별자와 요청 식별자를 보관하세요. 해당 작업의 동작 방식에 맞는 경우에만 다시 시도하세요. |
detail은 구체적인 실패 원인을 설명합니다. 상태 코드만으로는 오류를 완전히 분류할 수 없습니다. 프록시 또는 네트워크 오류로 인한 응답에는 문제 본문이 없을 수 있습니다. 진단을 위해 HTTP 상태와 읽을 수 있는 응답 텍스트를 보관하되, 비밀 정보는 로그에 기록하지 마세요.
현지화 제출 다시 시도하기 #
생성 요청을 보내기 전에 해당 요청의 Idempotency-Key을 저장하세요. 응답이 유실되면 같은 키로 동일한 생성 요청을 다시 보내 원래 작업을 조회하세요. 새 키를 사용하면 새 작업이 생성됩니다.
작업을 생성한 후에는 작업 식별자를 저장하세요. 다른 작업을 생성할지 결정하기 전에 기존 작업을 조회하세요. 업로드에는 SHA-256 주소가 가리키는 바이트를 정확히 사용해야 합니다. 작업을 시작하기 전에 누락된 업로드를 모두 완료하세요. /start을 반복해도 동일한 작업에 적용됩니다.
작업을 시작할 때 실행 가능 여부를 확인합니다. DailyTokenLimitReached 또는 크레딧 부족으로 시작하지 못한 작업은 대기 상태로 유지되며, 계정 문제가 해결되면 나중에 시작할 수 있습니다. 새 작업을 반복해서 생성해도 계정 한도 문제는 해결되지 않습니다.
요청 실패와 작업 실패 구분하기 #
GET /v2/localization/jobs/:id에서 HTTP 200을 반환하면 작업 조회에 성공했다는 뜻입니다. 하지만 해당 작업의 status._tag는 여전히 Failed일 수 있습니다. status.message, 각 대상의 상태, 단계별 경고 및 실패를 확인하세요.
다른 대상이 실패하더라도 완료된 대상은 계속 다운로드할 수 있습니다. 완료된 대상은 보관하고, 원인을 해결한 뒤 다시 생성해야 하는 작업만 제출하세요. 클라이언트의 폴링 시간이 초과되어도 작업은 취소되지 않습니다.
프로비저닝에는 별도의 유형별 결과 및 복구 방법이 있습니다. 검토 결정에는 별도의 종료된 검토 및 유효하지 않은 수정 오류가 있습니다. 실패할 때마다 원래 쓰기 요청을 반복하기보다는 해당 리소스의 상태를 기준으로 복구 방법을 판단하세요.