오류 처리

에러 응답을 코드로 분기하고 안전한 재시도 및 문의 기준을 찾으세요.

AI 게이트웨이 오류는 status와 type으로 분기하고, error_ref는 문의 시 추적 식별자로 사용합니다.

오류 응답 구조

Letsur AI 게이트웨이 API 키로 호출하면 에러는 다음 JSON 구조로 내려옵니다.


{
  "type": "<에러 코드>",
  "title": "<짧은 제목>",
  "status": <HTTP 상태 코드>,
  "detail": "<원인을 설명하는 본문>",
  "error_ref": "<문의 시 전달할 식별자>"
}

필드	설명
`type`	클라이언트가 분기할 에러 코드입니다
`title`	사람이 읽기 위한 짧은 제목입니다
`status`	HTTP 상태 코드와 같은 값입니다
`detail`	원인을 설명하는 문장입니다. 프로그램의 분기 기준으로 사용하지 않습니다
`error_ref`	문의 시 전달할 요청 식별자입니다

오류를 기록할 때 HTTP 상태, type, error_ref를 함께 저장합니다. API 키 값이나 전체 인증 헤더는 로그와 문의 내용에 남기지 않습니다.

표에 없는 에러도 status와 type을 기준으로 처리하고, detail은 진단용으로만 사용합니다.

`type`	HTTP	먼저 확인할 것
`invalid_credentials` / `missing_credentials`	401	인증의 경로별 헤더와 키 값을 확인합니다
`api_key_expired`	401	키의 만료일과 현재 사용할 수 있는 키를 확인합니다
`insufficient_units`	402	유닛에서 보유 유닛과 차단 상태를 확인합니다. 같은 요청을 반복해도 시간이 지나서 자동 복구되지 않습니다
`ip_not_allowed`	403	요청을 보내는 서버의 출발지 IP가 키의 IP 허용 목록에 포함됐는지 확인합니다
`usage_limit_exceeded`	429	해당 API 키의 월 한도를 확인합니다
`rate_limit_exceeded`	429	응답의 안내를 확인하고 간격을 두고 재시도합니다
`invalid_parameter` / `validation_error`	400	`detail`을 확인하고 요청 필드를 수정합니다
`invalid_image_file` / `image_fetch_error`	400	이미지 파일의 형식, 크기와 읽기 가능 여부를 확인한 뒤 다시 보냅니다
`invalid_model`	400	모델은 존재하지만 선택한 엔드포인트에서 지원하지 않습니다. 에셋에서 지원 API를 확인합니다
`context_length_exceeded`	400	입력을 줄이고 에셋에서 모델의 현재 컨텍스트를 확인합니다
`model_not_found`	404	에셋에서 모델 코드와 지원 엔드포인트를 확인합니다
`service_error` / `proxy_error`	502	간격을 두고 재시도한 뒤 계속되면 `error_ref`와 함께 문의합니다
`service_timeout`	504	간격을 두고 재시도한 뒤 계속되면 `error_ref`와 함께 문의합니다

상태	대응
429 `rate_limit_exceeded`	응답에 재시도 안내가 있으면 따르고, 없으면 간격을 늘려 재시도합니다
429 `usage_limit_exceeded`	반복 재시도하지 말고 해당 키의 월 한도를 확인합니다
402 `insufficient_units`	반복 재시도하지 말고 보유 유닛과 차단 상태를 확인합니다
5xx	짧은 간격으로 반복 호출하지 말고 간격을 늘려 제한적으로 재시도합니다
그 밖의 4xx	요청, 인증, 모델 코드를 수정한 뒤 다시 호출합니다

재시도 후에도 같은 오류가 계속되면 렛서 플랫폼에 로그인한 뒤 플랫폼 내 문의 기능을 사용합니다. 요청 시각, 엔드포인트, HTTP 상태, type, error_ref를 남기고, API 키나 전체 인증 헤더는 보내지 않습니다.