에러 코드

Gateway의 모든 에러 응답은 RFC 7807 Problem Details 표준을 따릅니다. 응답 본문만 보고 원인과 대응을 판단할 수 있습니다.

응답 포맷

모든 에러는 같은 JSON 구조로 내려옵니다.


{
  "type": "https://gw.letsur.ai/errors/<error-code>",
  "title": "<짧은 제목>",
  "status": <HTTP 상태 코드>,
  "detail": "<사용자가 읽는 본문>",
  "instance": "<요청을 식별하는 URI>",
  "error_ref": "<문의 시 전달할 식별자>"
}

자주 만나는 에러

아래 표는 자주 만나는 에러입니다. 표에 없는 에러는 응답의 type으로 직접 분기합니다.

코드	HTTP	의미	대응	재시도
`unauthorized`	401	키가 없거나 만료·폐기됨	키 상태를 확인합니다(키 라이프사이클). 필요하면 새 키를 발급합니다	×
`forbidden`	403	권한 없음(Member가 Admin 전용 엔드포인트 호출 등)	권한을 확인합니다(역할). Admin에게 요청합니다	×
`key_limit_exceeded`	429	Key Limit 도달	`reset_at`까지 대기하거나 한도를 올립니다(Key Limit)	`reset_at` 후
`member_limit_exceeded`	429	Member Limit 도달	Admin에게 한도 상향을 요청합니다(Member Limit)	`reset_at` 후
`service_limit_exceeded`	429	Service Limit 도달	Admin에게 신고합니다(Service Limit)	`reset_at` 후
`invalid_parameter`	400	파라미터 값 오류	본문 `detail`과 `param`을 확인하고 요청을 고칩니다	×
`model_not_found`	404	카탈로그에 없는 모델	카탈로그에서 정확한 모델 코드를 확인합니다	×
`context_length_exceeded`	400	프롬프트와 응답이 모델 컨텍스트를 초과	프롬프트를 줄이거나 컨텍스트가 더 큰 모델을 씁니다	×
`service_error`	5xx	처리 중 오류	`error_ref`와 함께 문의합니다	exponential backoff

모든 에러 응답에는 요청 식별자 error_ref가 들어갑니다. 문의할 때 이 값을 첨부하면 문제를 더 빠르게 확인할 수 있습니다.

어떤 에러든 응답의 error_ref를 미리 저장해 두세요. customer.service@letsur.ai로 문의할 때 이 값을 함께 전달합니다.

재시도

코드	재시도
429	응답 본문의 `reset_at`(또는 `retry_after`)까지 대기한 뒤 재시도합니다
5xx	exponential backoff로 재시도합니다(초기 1s, 최대 30s, 5회까지)
4xx(위 제외)	재시도하지 않습니다. 같은 요청은 같은 에러를 받으므로 요청을 고칩니다

에러 코드

응답 포맷

자주 만나는 에러

재시도

관련 문서