오류 및 상태 코드

API 문제 응답을 해석하고 실패한 요청을 복구하는 방법, HTTP 오류와 번역 작업 실패를 구분하는 방법을 알아보세요.

성공 응답을 디코딩하기 전에 HTTP 상태를 확인하세요. https://api.lingo.dev/v2의 API는 실패 정보를 JSON 형식의 문제 세부 정보로 반환합니다. 작업 조회에 성공했더라도 실제 작업은 실패했을 수 있으므로 작업 상태도 확인하세요.

문제 응답 읽기 #

문제 응답은 Content-Type: application/problem+json을 사용합니다. 공통 필드는 type, title, status, detail입니다. 이름이 지정된 문제에는 영향을 받는 리소스나 해결 방법을 식별하는 필드도 포함됩니다.

다음은 현지화 작업을 찾을 수 없을 때의 응답 예시입니다.

json
{
  "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가 나열됩니다.

json
{
  "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, 각 대상의 상태, 단계별 경고 및 실패를 확인하세요.

다른 대상이 실패하더라도 완료된 대상은 계속 다운로드할 수 있습니다. 완료된 대상은 보관하고, 원인을 해결한 뒤 다시 생성해야 하는 작업만 제출하세요. 클라이언트의 폴링 시간이 초과되어도 작업은 취소되지 않습니다.

프로비저닝에는 별도의 유형별 결과 및 복구 방법이 있습니다. 검토 결정에는 별도의 종료된 검토 및 유효하지 않은 수정 오류가 있습니다. 실패할 때마다 원래 쓰기 요청을 반복하기보다는 해당 리소스의 상태를 기준으로 복구 방법을 판단하세요.