오류 처리
오류 원인과 요청 단계에 따른 복구 판단
모델 호출과 작업 및 파일 API의 오류 형식을 구분하고, 응답을 받지 못했을 때의 재시도 기준과 지원 문의에 필요한 진단 정보를 설명합니다.
페이지 목차
상황별 대응
AI 게이트웨이 API에서 오류를 받았거나 응답을 받지 못했다면 오류가 발생한 요청의 종류와 이미 받은 식별자를 먼저 확인하세요. 응답을 받지 못했더라도 원래 요청은 처리됐을 수 있으며, 같은 요청을 다시 보내면 비용이 다시 발생할 수 있습니다.
| 지금 상황 | 확인할 곳 |
|---|---|
| 응답을 받지 못했거나 timeout 또는 5xx가 발생함 | 요청 단계별 재시도 기준에서 원래 요청이 처리됐는지 확인하는 방법을 찾고, 새 호출 여부를 판단합니다 |
| 공통 모델 호출의 오류 코드를 받음 | 오류 type별 대응에서 확인할 설정이나 요청 필드를 찾습니다. 공통 모델 호출 오류에는 type과 error_ref가 포함됩니다. 각 필드의 의미는 오류 응답 구조에서 확인합니다 |
| 이미지 생성 요청이 거절됐거나, 영상 또는 이미지 작업을 조회하거나 파일을 받는 중 오류가 남 | 작업과 파일 오류를 확인합니다. 이 API들은 오류 코드로 error.code를 사용하기도 합니다 |
| Batch 작업을 조회하거나 파일을 받는 중 | 작업 생성, 조회, 취소는 Batches의 오류 안내를, 입력 파일 업로드와 결과 다운로드는 Batch Files의 오류 안내를 따릅니다 |
재시도할 수 있는 경우
먼저 실패한 요청이 어느 단계의 요청인지 확인합니다. 단계는 동기 호출, 비동기 작업 생성, 파일 업로드, 조회 네 가지입니다. 동기 호출에 속하는 요청은 다음과 같습니다.
- Chat Completions, Responses, Messages, Embeddings
- Image Edits와, 결과를 응답 본문으로 받는 모델의 Image Generations
- 작업 ID를 반환하는 모델에
Prefer: respond-async헤더 없이 보낸 Image Generations 요청. 응답에 작업 ID가 있으면 새 요청을 보내기 전에 그 작업을 조회합니다.
Prefer: respond-async 헤더를 붙여 보낸 요청은 비동기 작업으로 접수되므로 작업 ID로 조회합니다. 어느 모델이 어느 경우인지는 Image Generations의 지원 모델에 있습니다.
같은 요청을 다시 보내면 별도 호출로 처리되어 비용이 추가될 수 있으므로 자동 반복을 멈추고, 요청 단계에 따라 아래 표를 따릅니다. 일부 SDK는 503 같은 5xx 응답을 받으면 요청을 자동으로 재시도합니다. 새 생성을 반복하지 않도록 클라이언트의 자동 재시도 설정도 확인하세요.
| 실패한 요청 | 다음 행동 |
|---|---|
| 위 목록의 동기 호출 | 새 호출이 필요한지 판단합니다. 원래 호출의 비용을 확인해야 한다면 진단 정보를 준비해 문의합니다 |
| 영상 생성 POST | 작업 ID가 있으면 같은 ID로 조회합니다. ID를 받지 못했다면 새 POST를 보내지 말고 접수 여부 확인에서 안내하는 정보로 문의합니다 |
| Batch 파일 업로드 또는 제출 | 각 API의 재시도 기한 안에 같은 요청 키와 원래 본문으로 요청을 다시 보내 원래 요청의 접수 결과를 확인합니다. 업로드와 제출의 Idempotency-Key는 서로 다른 요청에 적용됩니다 |
| 작업 또는 파일 조회 | 작업을 새로 생성하거나 제출하지 않습니다. 같은 식별자로 조회하되 요청 간격을 늘리고 재시도 횟수를 제한합니다 |
| 위 행에 없는 공통 모델 호출의 4xx | 응답 상세에 따라 요청, 인증 또는 모델 코드를 수정한 뒤 다시 호출합니다. 작업과 파일 API의 오류는 각 명세를 따릅니다 |
Batch에서는 같은 Idempotency-Key로 다시 보내 접수 결과를 확인할 수 있지만, 게이트웨이는 동기 호출에 이 중복 방지 방식을 적용하지 않습니다.
분석 화면은 누적 사용량을 보여 주므로 그 값만으로 응답을 잃은 특정 호출의 실행 여부나 비용을 확정할 수 없습니다.
비스트리밍 채팅의 응답 대기 시간 초과
POST /v1/chat/completions를 stream: false(기본값)로 호출한 뒤 504 gateway_timeout을 받으면 같은 요청을 자동으로 다시 보내지 마세요. 시간이 초과돼도 이전 생성은 취소되지 않았을 수 있고, 비용도 발생했을 수 있습니다.
응답에 x-should-retry: false 헤더가 있으면 자동으로 다시 보내지 말라는 뜻입니다. 다만 이 헤더가 모든 504나 스트리밍 오류에 포함되지는 않고, 브라우저에서는 게이트웨이 응답의 CORS 설정에 따라 헤더를 읽지 못할 수도 있습니다. 헤더가 없거나 읽을 수 없어도 다시 보내도 된다고 해석하지 말고, 위 요청 단계별 기준을 따르세요.
| 하려는 일 | 다음 행동 |
|---|---|
| 자동 재시도 막기 | 사용하는 SDK나 HTTP 클라이언트가 x-should-retry 헤더를 지원하는지 확인하고, 확인하기 어렵다면 자동 재시도를 끕니다. Chat Completions의 SDK 예제는 자동 재시도를 끈 설정을 보여줍니다 |
| 원래 호출의 처리 여부나 비용 확인 | 진단 정보를 준비해 문의합니다 |
| 새 호출 보내기 | 모델의 지원 범위 안에서 출력 한도를 줄이거나 스트리밍을 검토합니다. 스트리밍도 중단될 수 있으며 이전 호출의 비용을 없애지는 않습니다 |
오류 응답 구조
공통 모델 호출 오류는 다음 JSON 구조로 반환됩니다. 작업 조회, 참조 파일 업로드와 파일 링크 발급에는 error.code를 사용하는 오류도 있으므로 작업 조회, References, 파일 링크 발급의 응답 형식을 따릅니다. 작업 ID를 반환하는 이미지 모델로 보낸 요청의 HTTP 오류에는 error.code와 error.message가 반환되므로 Image Generations의 작업 ID를 반환하는 모델의 오류를 따릅니다.
Batch 작업과 파일의 오류 형식은 Batches와 Batch Files에서 확인합니다. 영상 파일의 링크 발급 절차를 Batch 결과 다운로드에 적용하지 않습니다.
| 필드 | 설명 |
|---|---|
type | 클라이언트가 분기할 오류 코드입니다 |
title | 사람이 읽기 위한 짧은 제목입니다 |
status | HTTP 상태 코드와 같은 값입니다 |
detail | 원인을 설명하는 문장입니다. 프로그램의 분기 기준으로 사용하지 않습니다 |
error_ref | 문의할 때 전달할 오류 참조값입니다 |
아래 예시의 400은 구조를 설명하기 위한 값입니다. 실제 HTTP 상태와 status는 응답에서 확인합니다.
{
"type": "<에러 코드>",
"title": "<짧은 제목>",
"status": 400,
"detail": "<원인을 설명하는 본문>",
"error_ref": "<문의 시 전달할 식별자>"
}이 형식의 오류를 받으면 HTTP 상태, type, error_ref를 함께 저장합니다.
오류 type별 대응
위 공통 형식으로 반환된 오류는 표에 없더라도 status와 type을 기준으로 처리하고, detail은 진단용으로만 사용합니다.
| 오류 | 원인과 할 일 |
|---|---|
invalid_credentials / missing_credentials (401) | 인증의 경로별 헤더와 키 값을 확인합니다. invalid_credentials라면 AI 게이트웨이 > API 키에서 키가 비활성 상태이거나 삭제되지 않았는지도 확인합니다 |
api_key_expired (401) | 키의 만료일이 지났습니다. 만료된 키는 다시 활성화하거나 만료일을 바꿀 수 없으므로 새 키로 전환합니다 |
insufficient_units (402) | 유닛에서 보유 유닛과 차단 상태를 확인합니다. 같은 요청을 반복하거나 시간이 지나도 자동으로 복구되지 않습니다 |
ip_not_allowed (403) | 키의 IP 허용 목록에 요청을 보내는 서버의 출발지 IP가 포함되어 있는지 확인합니다 |
overage_not_allowed (403) | code 값은 OVERAGE_NOT_ALLOWED입니다. Batch를 사용하려면 보유 유닛과 관계없이 초과 유닛 사용이 허용되어 있어야 합니다. Batch 시작 전 준비에서 허용 여부와, 허용이 필요할 때 문의하는 방법을 확인합니다. 유닛 구매만으로는 해결되지 않습니다 |
policy_limit_exceeded (429) | 한도 정책이 요청을 거부했습니다. 적용 대상과 정책을 확인하는 순서는 한도에 도달했을 때에 있습니다 |
usage_limit_exceeded (429) | 사용 제한에 도달했습니다. 적용 대상과 해제 조건은 한도에 도달했을 때에서 확인합니다 |
rate_limit_exceeded (429) | 응답의 안내를 확인하고 간격을 두고 재시도합니다 |
invalid_parameter / validation_error (400) | detail을 확인하고 요청 필드를 수정합니다 |
content_policy_violation (400) | 모델 공급사가 콘텐츠 정책에 따라 요청을 거절했습니다. 같은 요청을 자동 반복하지 말고 입력과 모델의 이용 조건을 확인합니다 |
invalid_image_file / image_fetch_error (400) | 이미지 파일의 형식, 크기와 읽기 가능 여부를 확인한 뒤 다시 보냅니다 |
invalid_model (400) | 모델은 존재하지만 선택한 엔드포인트가 그 모델을 지원하지 않습니다. 에셋에서 지원 API를 확인합니다 |
context_length_exceeded (400) | 에셋에서 모델의 현재 컨텍스트 한도를 확인하고 입력을 줄입니다 |
model_not_found (404) | 에셋에서 모델 코드와 지원 엔드포인트를 확인합니다 |
service_error / proxy_error (502) | 조회 요청과 새 생성 요청은 재시도했을 때의 결과가 다릅니다. 앞의 요청 단계별 재시도 기준을 따릅니다 |
service_unavailable (503) | 서비스 또는 모델 공급 경로를 이용할 수 없습니다. 고객의 유닛 부족을 뜻하는 402와 구분합니다. 유닛 구매로 해결되는 오류로 판단하지 말고 요청 단계별 재시도 기준을 따릅니다 |
gateway_timeout (504) | 비스트리밍 채팅의 응답 대기 시간이 초과됐다면 채팅 타임아웃 처리를 확인합니다. 그 밖의 요청은 요청 단계별 재시도 기준을 따릅니다 |
service_timeout (504) | 제한시간 안에 응답을 받지 못했습니다. 원래 요청이 처리되지 않았다고 단정하지 말고 요청 단계별 재시도 기준을 따릅니다 |
콘텐츠 정책 거절의 HTTP 400과 성공 응답 안의 finish_reason: content_filter는 응답 형태가 다릅니다. 후자는 Chat Completions의 응답 종료 이유를 따릅니다. 오류 코드만으로 실행 여부나 비용 미발생을 판단하지 않습니다.
작업과 파일 오류
모델과 관계없이 오류가 생성 요청 접수, 작업 조회, 파일 수령 가운데 어디에서 났는지부터 확인합니다.
| 오류가 난 곳 | 다음 행동 |
|---|---|
Image Generations의 HTTP 429 queue_full | 작업 대기열 전체나 스페이스의 대기 작업 수, 또는 처리 한도에 도달해 새 요청을 받지 않았습니다. 이미 접수한 작업에는 영향이 없습니다. 응답 헤더 Retry-After의 초만큼 기다린 뒤 다시 보내고, 반복되면 간격을 늘립니다. 이 오류는 error.code로 반환됩니다. Image Generations의 작업 ID를 반환하는 모델의 오류 참고 |
| 작업 조회의 HTTP 503 | 생성 실패로 처리하거나 새 생성 요청으로 자동 재시도하지 않습니다. 작업 ID를 받았다면 같은 작업을 조회합니다 |
| 비동기 작업으로 접수된 요청의 실패 | 공급사의 콘텐츠 심사 거절은 HTTP 400이 아니라 실패한 작업으로 나타날 수 있습니다. 작업의 error.type을 확인합니다. 이미지 작업의 값은 Image Generations의 작업 실패 사유에, 영상 작업의 모델별 대응은 각 모델 가이드에 있습니다. 생성된 오디오가 심사를 통과하지 못해 작업이 실패하는 경우는 Seedance 2.0 가이드의 오디오 생성에 있습니다 |
| 파일 준비 중, 다운로드 링크 만료, 파일 보관 만료 | 결과 파일 받기를 따릅니다 |
| 링크 발급 요청의 오류, 반환된 링크를 열 때의 오류 | 두 경우를 나누어 파일 링크 발급에서 확인합니다 |
지원에 전달할 정보
원인을 해결하지 못했거나 원래 요청의 처리 여부를 확인해야 한다면 렛서 플랫폼에 로그인한 뒤 플랫폼 내 문의 기능을 사용합니다. 다음 정보를 남기세요.
- 스페이스 이름과 요청 시각
- 모델 코드와 엔드포인트
- HTTP 상태와 확보한
type또는error.code,error_ref - 확보한 작업 ID 또는 Batch ID
API 키나 전체 인증 헤더는 보내지 않습니다.