자주 묻는 질문
시작부터 에러까지, 자주 나오는 질문을 주제별로 묶었습니다. 답마다 더 자세한 페이지로 링크를 달아 뒀으니 필요하면 따라갑니다. 처음 보는 용어는 용어집에서 찾을 수 있습니다.
시작
Q. AI Gateway가 뭔가요? A. 여러 AI 공급사의 모델을 키 하나·주소 하나로 호출하게 해주는 서비스입니다. 공급사마다 따로 연동하지 않아도 됩니다. 자세히는 AI Gateway 퀵스타트에서 확인합니다.
Q. 좌측 메뉴에 AI Gateway가 안 보입니다. A. 아직 Space에서 켜지지 않은 상태입니다. Admin에게 활성화를 요청합니다. 누가 Admin인지 모르면 Space 설정의 멤버에서 확인할 수 있습니다. 자세히는 Gateway 활성화에서 확인합니다.
Q. 첫 호출은 어떻게 보내나요?
A. 모델 코드를 고르고, 키를 발급받고, base URL https://gw.letsur.ai/v1 로 호출하면 됩니다. 5분이면 충분합니다. 자세히는 AI Gateway 퀵스타트에서 확인합니다.
키·인증
Q. 키를 잃어버렸습니다. 다시 볼 수 있나요? A. 아니요, 키는 발급할 때 한 번만 보입니다. 기존 키는 폐기하고 새 키를 발급합니다. 자세히는 키 라이프사이클에서 확인합니다.
Q. 키는 어디에 넣나요?
A. OpenAI 호환 경로는 Authorization: Bearer <API_KEY> 헤더에 넣습니다. Anthropic 네이티브 경로(/v1/messages)는 x-api-key 헤더를 씁니다. 자세히는 Chat Completions에서 확인합니다.
Q. 401 api_key_not_found 가 떨어집니다.
A. 키가 틀렸거나 폐기·만료됐습니다. 키 목록에서 상태를 확인하고, base URL 끝에 /v1 이 있는지도 봅니다(OpenAI 호환 경로). 자세히는 401 인증 에러에서 확인합니다.
Q. 키를 코드에 그대로 적어도 되나요? A. 안 됩니다. 노출되면 즉시 폐기하고 새 키를 발급해야 합니다. 환경변수나 시크릿 매니저에 보관합니다. 자세히는 키 라이프사이클에서 확인합니다.
모델·호출
Q. 모델 코드는 어디서 확인하나요? A. AI Gateway의 카탈로그 탭에서 모델 코드·지원 엔드포인트·단가를 봅니다. 자세히는 에셋 카탈로그에서 확인합니다.
Q. 공급사를 바꾸려면요?
A. model 값만 다른 모델 코드로 바꾸면 됩니다. 주소·키·요청 형식은 그대로입니다. openai/ 같은 prefix는 붙이지 않습니다. 자세히는 Chat Completions에서 확인합니다.
Q. OpenAI SDK 코드를 그대로 쓸 수 있나요?
A. 네, base_url(https://gw.letsur.ai/v1)과 키만 바꾸면 됩니다. 자세히는 외부 도구 연동에서 확인합니다.
Q. Claude Code나 Anthropic SDK도 되나요?
A. 됩니다. Anthropic 네이티브 경로(/v1/messages)로 동작합니다. base URL은 /v1 없이 https://gw.letsur.ai 로 지정합니다. 자세히는 Claude Code 연동에서 확인합니다.
Q. Cursor도 연동되나요? A. 현재는 안 됩니다. Cursor는 외부 OpenAI 호환 엔드포인트를 그대로 받지 못하는 알려진 문제가 있습니다. 자세히는 알려진 미지원에서 확인합니다.
Q. 스트리밍으로 받고 싶습니다.
A. 요청에 "stream": true 를 넣으면 토큰이 실시간으로 옵니다. stream_options.include_usage: true 를 함께 주면 마지막 직전 청크에 usage 와 estimated_cost 가 들어옵니다. 자세히는 Chat Completions 스트리밍에서 확인합니다.
비용·한도
Q. 이번 호출이 얼마인지 어떻게 보나요?
A. 모든 응답에 estimated_cost 필드가 붙습니다. estimated_cost.amount(USD)에서 예상 원가를 바로 확인할 수 있습니다. 자세히는 요금에서 확인합니다.
Q. estimated_cost 가 실제 청구와 같은가요?
A. 호출 시점의 예상 비용입니다. 대시보드 반영까지 시간이 조금 걸릴 수 있습니다. 자세히는 요금에서 확인합니다.
Q. 이번 달 사용량은 어디서 보나요? A. 좌측 메뉴에서 AI Gateway를 열고 사용량에서 봅니다. Admin은 멤버별·키별로도 볼 수 있습니다. 자세히는 사용량 분석에서 확인합니다.
Q. 한도를 안 정하면 어떻게 되나요? A. 한도가 비어 있으면 무제한으로 동작합니다. 본격적으로 쓰기 전에 합의된 월 예산을 꼭 설정하기를 권장합니다. 자세히는 한도 개요에서 확인합니다.
Q. 429 usage_limit_exceeded 가 떨어집니다.
A. 키의 월 한도를 넘었습니다. 다음 달 리셋(매월 1일 00:00 KST)을 기다리거나, Admin에게 한도 상향을 요청합니다. 자세히는 한도 개요에서 확인합니다.
에러
Q. 에러 응답은 어떻게 생겼나요?
A. 모든 에러가 RFC 7807 형식(type·title·status·detail·error_ref)으로 옵니다. 코드 분기는 type 값으로 합니다. 자세히는 에러 코드에서 확인합니다.
Q. error_ref 는 뭔가요?
A. 에러마다 붙는 추적용 식별자입니다(예: err_a3f2c1d8e5b0). 문의할 때 이 값을 함께 전달하면 정확히 추적됩니다. 자세히는 에러 코드에서 확인합니다.
Q. 502/504 가 떨어집니다.
A. 공급사 쪽 일시적 문제입니다. 잠시 후 재시도하면 대부분 통합니다. 계속되면 error_ref 와 함께 문의합니다. 자세히는 502·504 업스트림 에러에서 확인합니다.
Q. 어떤 에러는 재시도하고 어떤 건 하면 안 되나요? A. 502·504는 backoff로 재시도, 429는 리셋까지 대기 후 재시도, 400·401·403은 요청/키를 고치기 전까지 재시도해도 똑같이 막힙니다. 자세히는 에러 코드의 재시도 기준에서 확인합니다.
더 막힐 때
위에서 답을 못 찾았다면 customer.service@letsur.ai 로 문의합니다. 에러가 있었다면 응답의 error_ref 값을 함께 전달하면 훨씬 빠릅니다.