개발 환경에서는 호출이 잘 됩니다. 이제 프로덕션에서 돌아갈 부분, 즉 catch 블록을 작성할 차례입니다. 서드파티 API의 HTTP 오류는 그 자체만으로는 불친절합니다. 빨간 상태 코드 하나만 보일 뿐, 새벽 3시에 정말 알고 싶은 단 하나의 답, 이게 내 요청 문제인지, 내 키 문제인지, 내 요금제 문제인지, 아니면 상대 서버 문제인지는 바로 드러나지 않으니까요. 그리고 이 중 무엇은 재시도해야 하고, 무엇은 사용자에게 보여줘야 할까요?
Lingo.dev는 여기에 명확한 구조를 줍니다. 동기식이든 비동기식이든, 어떤 엔드포인트에서 발생한 오류든 모두 하나의 고정된 표에 있는 상태 코드와 함께 같은 JSON 객체 형식으로 돌아옵니다. 상태 코드는 단순한 라벨이 아니라 다음 행동을 알려주는 신호입니다. 요청을 고쳐야 하는지, 키를 교체해야 하는지, 계정을 충전해야 하는지, 잠시 물러나야 하는지, 아니면 재시도해야 하는지를 알려줍니다. 코드만 읽어도 다음 액션이 보입니다. 상태 코드를 기준으로 한 하나의 오류 핸들러로 전체 API를 처리할 수 있습니다.
이 페이지에서 다루는 내용
오류 형식#
2xx가 아닌 모든 응답은 같은 본문을 가집니다. 무엇이 잘못됐는지 설명하는 message 필드 하나만 담긴 JSON 객체입니다.
{
"message": "Invalid API key"
}이것이 계약의 전부입니다. 따로 벗겨낼 래퍼도 없고, 엔드포인트마다 예외 처리해야 하는 오류 형식도 없습니다. /process/localize의 400이든 작업 조회의 404든 반환 형식은 같고, 달라지는 것은 상태 코드와 message 텍스트뿐입니다.
메시지 텍스트가 아니라 상태 코드를 기준으로 처리하세요
HTTP 상태 코드는 흔들리지 않는 신호입니다. 오류 처리는 이 값을 기준으로 분기하세요. message 문자열은 로그를 읽는 사람이 이해하도록 쓴 문구일 뿐입니다. 기계가 읽는 오류 코드로 취급하지 말고, 정확한 문장에 패턴 매칭하지도 마세요.
상태 코드#
총 7개의 상태 코드로 모든 응답을 설명할 수 있습니다. 여기서는 누가 이 문제를 해결해야 하는지를 기준으로 묶었습니다. 이 분류가 곧 재시도 정책이기도 합니다.
요청 자체로는 처리할 수 없는 내용을 보낸 경우(요청을 수정하고, 무작정 재시도하지 마세요):
| 상태 | 의미 |
|---|---|
400 Bad Request | 요청 검증 실패 – 필드 누락, 잘못된 로캘, HTTP(HTTPS 아님) callbackUrl, 형식이 잘못된 페이로드 등이 원인일 수 있습니다. |
401 Unauthorized | X-API-Key 헤더가 없거나 올바르지 않습니다. 인증을 참고하세요. |
403 Forbidden | 키는 유효하지만 요청한 리소스에 접근할 권한이 없습니다. |
404 Not Found | 해당 리소스(엔진, 작업, 작업 그룹)가 존재하지 않습니다. |
조직이 계정 한도에 도달한 경우(결제에서 해결):
| 상태 | 의미 |
|---|---|
402 Payment Required | 조직이 크레딧 한도에 도달했습니다. |
429 Too Many Requests | 조직이 일일 토큰 한도에 도달했습니다. 한도를 늘리려면 요금제를 업그레이드하세요. |
우리 쪽에서 문제가 발생한 경우(일시적 문제 – 재시도):
| 상태 | 의미 |
|---|---|
500 Internal Server Error | 예기치 않은 실패입니다. 데이터베이스 오류이거나, 엔진에 구성된 모든 모델에서 번역 호출이 실패한 경우일 수 있습니다. |
401와 403는 비슷해 보여도 같은 문제가 아닙니다. 401는 호출자를 아예 식별하지 못했다는 뜻이고, 403는 키는 식별했지만 접근이 허용되지 않았다는 뜻입니다. 401는 키 자체를 해결해야 하는 문제(교체하거나 확인)이고, 403는 키의 접근 권한을 해결해야 하는 문제입니다.
재시도해야 할 오류#
까다로운 통합 담당자가 오류 표를 볼 때 가장 먼저 묻는 질문은 대개 이것입니다. 그래서 뭘 재시도해야 하죠? 위의 분류가 바로 그 답입니다.
- 4xx – 무작정 재시도하지 마세요.
400,401,403,404는 모두 내 요청 쪽 문제를 설명합니다. 같은 요청을 그대로 다시 보내면 같은 오류가 그대로 반복됩니다. 입력값, 키, 리소스 ID를 수정한 뒤 다시 보내세요. - 402와 429 – 잠시 멈추고, 한도 문제를 해결하세요. 이 오류들은 요청 단위의 일시적인 문제가 아닙니다. 근본 원인인 한도가 바뀌기 전까지는 다음 요청도 같은 벽에 막힙니다. 짧은 간격으로 계속 재시도하지 말고, 한도 문제를 드러낸 뒤 해결하세요(충전하거나 요금제를 업그레이드).
- 500 – 백오프를 두고 재시도하세요. 이 경우만이 진짜로 일시적일 수 있는 오류입니다.
500는 해당 호출에서 구성된 모든 모델이 타임아웃됐다는 뜻일 수 있고, 재시도하면 정상적인 모델로 처리될 수도 있습니다. 지수 백오프와 재시도 상한을 함께 사용하세요.
비동기 API는 결과를 다르게 전달합니다
이 재시도 정책은 직접 호출하는 동기식 요청에 대한 것입니다. 비동기 로컬라이제이션 API는 작업 결과를 상태 코드로 돌려주지 않습니다. POST는 요청이 수락되면 202를 반환하고, 각 대상 로캘은 내구성 있는 백그라운드 워크플로를 통해 각각 독립적인 작업으로 실행됩니다. 따라서 원래 호출에서 상태 코드를 잡는 대신, 작업을 폴링하거나 웹훅으로 결과를 받게 됩니다. 자세한 내용은 비동기 작업 오류가 기록되는 위치를 참고하세요.
402와 429: 서로 다른 두 가지 한도#
이 두 계정 수준 코드는 얼핏 비슷해 보입니다. 둘 다 "다 써버렸다"처럼 들리기 때문에, 둘을 혼동하면 개발자는 엉뚱한 해결책으로 가게 됩니다. 하지만 이 둘은 서로 다른 한도이고, 해결 방법도 다릅니다.
402 Payment Required– 조직이 크레딧 한도에 도달했습니다. 이는 결제 경계입니다. 조직의 결제 상태가 바뀌기 전까지 다음 호출도 계속 실패합니다.429 Too Many Requests– 조직이 일일 토큰 한도에 도달했습니다. 이는 시간이 지나면 초기화되는 사용량 상한이며, 요금제를 업그레이드해 한도를 높일 수 있습니다.
핸들러에서 이 둘을 구분해 둬야 하는 이유가 있습니다. 402는 사람이 직접 처리해야 하는 결제 조치이고, 429는 기다리거나 업그레이드로 풀 수 있는 사용량 한도입니다. 둘 다 뭉뚱그려 "결제 문제"라고 안내하면, 운영자가 실제로 어떤 레버를 당겨야 하는지 가려집니다.
402 응답 본문은 다른 오류와 똑같이 생겼습니다. 이것이 크레딧 한도 문제라는 사실은 상태 코드가 알려줍니다.
{
"message": "Organization has reached its credit limit"
}비동기 작업 오류가 기록되는 위치#
여기에는 분명히 선을 그어야 할 지점이 있습니다. 상태 코드 핸들러가 더 이상 적절한 도구가 아닌 곳이 바로 여기입니다.
이 페이지의 상태 코드는 전송 수준의 코드입니다. 즉, API가 여러분의 HTTP 요청을 받아들였는지, 그리고 처리할 수 있었는지를 설명합니다. 비동기 API의 202는 요청이 수락됐다는 뜻일 뿐, 번역이 성공했다는 뜻은 아닙니다. 비동기 작업은 문제없이 수락된 뒤에도 실행 중 모델이 타임아웃되면서 나중에 실패할 수 있습니다. 이런 실패는 원래 호출의 HTTP 상태 코드로 나타나는 것이 아니라, 작업 자체에 기록됩니다.
따라서 비동기 실패는 이 표가 아니라 아래 세 곳에서 드러납니다.
- 작업별 상태. 실패한 로캘은 작업에
status: "failed"와errorMessage를 가집니다. 작업 상태를 참고하세요. - 그룹 상태. 일부 로캘은 성공하고 일부는 실패하면, 그룹은
partial를 보고합니다. 성공한 로캘은 그대로 전달됩니다. 작업 그룹 추적을 참고하세요. - 웹훅 전달. 실패는
translation.failed이벤트로 전달되며, 여기에error필드가 포함됩니다. 웹훅 전달을 참고하세요.
많이들 헷갈리는 구분이 하나 더 있습니다. 중요하지 않은 pipeline 단계가 실패해도 작업 자체가 실패하는 것은 아닙니다. 이 경우 작업은 오류가 아니라 completed_with_warnings와 단계별 경고를 남긴 채 완료됩니다. 이것은 오류 코드 문제가 아니라 파이프라인 가시성의 문제입니다. 파이프라인 실행 관찰을 참고하세요.
다음 단계#
깔끔한 오류 핸들러는 통합 과정에서 가장 먼저 마주치게 될 두 지점부터 시작하면 됩니다. 바로 인증, 그리고 비동기 작업이 자체 결과를 드러내는 지점입니다.
