작성자 주: curl은 성공하지만 클라이언트에서 401, 404, 400 오류가 발생하거나 연결되지 않을 때, API 중계 서비스의 7가지 점검 항목을 순서대로 살펴봐요. 오류 코드 대조표와 10분 점검 체크리스트도 함께 제공합니다.
같은 API 키와 모델로 curl 요청을 보내면 200 응답을 받는데, Cherry Studio, Chatbox, Cursor, Cline, Claude Code 또는 Codex CLI에서는 401, 404, 400 오류가 발생하거나 아예 시간 초과, 빈 응답이 돌아오는 경우가 있어요. 이럴 때는 API 키부터 바꾸지 말고 클라이언트 설정을 먼저 의심하세요. curl이 성공했다면 API 키가 유효하고 네트워크에 연결할 수 있다는 뜻이에요. 클라이언트가 실제로 보내는 요청이 생각한 것과 다를 가능성이 큽니다.
권장 점검 순서는 Base URL → 프로토콜과 엔드포인트 → 인증 헤더 → 모델 ID → 요청 본문 → 네트워크입니다. 그 전에 클라이언트가 수정한 설정을 제대로 읽었는지부터 확인해야 해요. 이 글에서는 요청 경로를 7가지 점검 항목으로 나누고, 각 항목을 ‘증상, 원인, 확인 방법, 해결 방법’ 순서로 설명해요. 10분 안에 문제가 클라이언트, 게이트웨이, 업스트림 중 어디에 있는지 판단하는 것이 목표입니다.
단순히 API 원리를 설명하는 글이 아니라, 바로 따라 할 수 있는 문제 해결 가이드예요.
curl은 되는데 클라이언트는 연결되지 않는 이유: API 중계 서비스 점검 핵심
curl은 연결 경로의 일부만 확인해요. DNS 해석, TLS 핸드셰이크, 네트워크 연결, 키 유효성, 그리고 직접 요청한 단일 엔드포인트가 작동하는지 확인할 뿐이에요. 클라이언트가 수정한 설정을 읽었는지, Base URL을 어떻게 조합하는지, 요청 헤더와 본문이 curl과 일치하는지는 확인하지 않아요.
클라이언트에서 출발한 요청은 대략 다음 경로를 거쳐요. 클라이언트 설정(환경 변수, 설정 파일, GUI) → Base URL 조합 → 프로토콜과 엔드포인트 → 인증 헤더 → 모델 ID와 매핑 → 요청 본문(메시지, 도구, 멀티모달, 스트리밍) → 프록시, TLS, 네트워크 → 게이트웨이 → 업스트림 모델. curl이 성공했다는 건 직접 작성한 경로가 작동한다는 뜻일 뿐이에요. 클라이언트는 완전히 다른 경로로 요청할 수도 있어요.
| 점검 항목 | 대표적인 증상 | 우선 확인 방법 |
|---|---|---|
| 1. 설정 읽기 | 설정을 바꿔도 적용되지 않고 이전과 같은 오류 발생 | 클라이언트 로그에서 실제 요청 URL 확인 |
| 2. Base URL 조합 | 404 오류, 경로에 /v1/v1 또는 //가 나타남 |
로그의 URL과 curl URL 비교 |
| 3. 프로토콜과 엔드포인트 | 404, 400 오류 또는 응답 형식 파싱 실패 | 클라이언트가 사용하는 프로토콜 확인 |
| 4. 인증 헤더 | curl에서는 키가 정상인데 401 오류 발생 | 요청 헤더 차이 비교 |
| 5. 모델 ID | 404 또는 400 오류와 함께 모델이 없다는 메시지 표시 | 게이트웨이 모델 목록과 한 글자씩 비교 |
| 6. 요청 본문 | 일반 텍스트는 되지만 이미지나 도구를 추가하면 400 오류 발생 | 변수를 하나씩 추가하며 재현 |
| 7. 네트워크와 스트리밍 | 타임아웃, stream disconnected, 빈 응답 | 스트리밍을 끄고 비교한 뒤 프록시 확인 |
API 중계 서비스 점검 사항 1~2: 클라이언트 설정 적용과 Base URL 조합
점검 항목 1: 클라이언트가 변경한 설정을 읽고 있는지 확인
증상: Base URL과 API 키를 새 값으로 바꿨는데도 이전과 똑같은 오류가 나거나, 한 프로젝트에서는 되지만 다른 프로젝트에서는 동작하지 않아요.
원인: 대부분의 클라이언트는 여러 곳에서 설정을 읽어요. GUI 설정이 환경 변수를 덮어쓰거나, 설정 파일에 여러 프로필이 있어 수정한 프로필이 활성화되지 않았을 수 있어요. 프로젝트 설정이 전역 설정보다 우선하거나, 이전 프로세스가 종료되지 않아 시작할 때 불러온 옛 값을 계속 사용하는 경우도 있어요. 특히 명령줄 도구에서는 터미널에서 환경 변수를 바꿔도 이미 실행 중인 IDE나 Agent 프로세스에는 반영되지 않기 쉬워요.
확인 방법: 클라이언트 로그나 디버그 출력을 열어 실제 요청 URL과 API 키의 앞부분이 방금 바꾼 값과 일치하는지 확인하세요. 로그를 보기 어렵다면 Base URL을 일부러 명백히 잘못된 주소로 바꿔 오류가 달라지는지 확인해 보세요.
해결 방법: 먼저 클라이언트의 설정 우선순위를 확인하세요. 보통 GUI나 프로젝트 설정이 전역 설정 파일보다, 설정 파일이 환경 변수보다 우선하지만 클라이언트마다 다르므로 문서를 기준으로 삼아야 해요. 그런 다음 우선순위가 가장 높은 곳에서만 수정하고, 다른 위치의 충돌하는 설정을 삭제한 뒤 클라이언트 프로세스를 완전히 종료하고 다시 시작하세요.
점검 항목 2: Base URL의 끝 슬래시, /v1 중복과 경로 접두사
증상: 404 오류가 나고, 로그의 URL이 /v1/v1/chat/completions, //chat/completions 또는 /v1/chat/completions/chat/completions처럼 표시돼요.
원인: 클라이언트마다 Base URL 입력란을 해석하는 방식이 달라요. 루트 주소를 입력받아 /v1을 자동으로 붙이는 클라이언트도 있고, /v1까지 입력받은 뒤 /chat/completions를 붙이는 클라이언트도 있어요. Base URL과 전체 엔드포인트를 별도 입력란으로 구분하는 경우도 있어요. 접두사만 받는 입력란에 https://api.apiyi.com/v1/chat/completions 전체를 입력하거나, /v1이 포함된 주소 끝에 슬래시를 추가하면 조합된 경로가 잘못될 수 있어요.
확인 방법: 로그에 표시된 전체 요청 URL과 curl에 사용한 URL을 한 글자씩 비교하세요. 특히 /v1이 몇 번 나오는지, 슬래시가 중복됐는지, 끝에 경로가 더 붙었는지 살펴보세요.
해결 방법: 클라이언트 문서에 맞게 입력하세요. OpenAI 호환 클라이언트에는 보통 끝에 슬래시 없이 https://api.apiyi.com/v1을 입력해요. 클라이언트가 /v1을 자동으로 붙인다면 직접 입력한 /v1은 제거하세요. 수정 후 로그의 URL을 다시 확인해 최종 경로가 https://api.apiyi.com/v1/chat/completions와 같은 표준 형식인지 확인하세요.
🎯 설정 권장 사항: APIYI(apiyi.com)의 OpenAI 호환 접속 주소는
https://api.apiyi.com/v1이며, 공식 OpenAI SDK에서도 같은 형식으로 사용해요. 사용 가능한 모델 목록은 콘솔에서 확인하거나 같은 Base URL로 모델 목록 API를 요청해 가져올 수 있어요. 먼저 이 방법으로 API 키와 주소가 올바른지 확인한 뒤 클라이언트를 설정해 보세요.
API 중계 서비스 점검 항목 3~4: 프로토콜 엔드포인트와 인증 헤더
점검 항목 3: 프로토콜과 엔드포인트가 일치하는지 확인
증상: Base URL은 문제가 없어 보이는데도 404 또는 400 오류가 발생해요. 또는 요청은 성공했지만 클라이언트에서 “응답을 파싱할 수 없습니다”라는 오류가 뜨거나 빈 내용이 반환돼요.
원인: 주요 대규모 언어 모델 API에는 여러 프로토콜이 있어요. 클라이언트는 Chat Completions만 지원하는데 Responses만 제공하는 엔드포인트를 지정했을 수 있어요. Claude Code는 OpenAI Chat Completions가 아닌 Anthropic Messages 프로토콜을 사용해요. Gemini 네이티브 형식과 OpenAI 호환 형식도 경로와 요청 본문이 완전히 달라요. curl에서는 올바른 엔드포인트를 직접 지정했더라도, 클라이언트는 자체 기본 프로토콜로 요청할 수 있어요.
| 프로토콜 유형 | 대표 엔드포인트 경로 | 주로 사용하는 도구 | 인증 방식 |
|---|---|---|---|
| OpenAI Chat Completions | /v1/chat/completions |
Cherry Studio, Chatbox, Cline 등 다양한 클라이언트 | Authorization: Bearer |
| OpenAI Responses | /v1/responses |
최신 OpenAI 생태계 도구 | Authorization: Bearer |
| Anthropic Messages | /v1/messages |
Claude Code 등 Anthropic 네이티브 도구 | x-api-key와 anthropic-version |
| Gemini 네이티브 | 모델명을 경로로 사용하는 네이티브 API | Gemini 네이티브 SDK | 공식 문서와 게이트웨이 문서 참고 |
확인 방법: 클라이언트 로그에서 요청 경로의 마지막 부분을 보고 어떤 프로토콜을 사용하는지 확인하세요. 그런 다음 선택한 게이트웨이 엔드포인트가 해당 프로토콜을 지원하는지 살펴보세요. 클라이언트에 ‘제공업체 유형’이나 ‘API 형식’ 드롭다운 메뉴가 있다면 사용할 프로토콜과 일치하는지도 확인하세요.
해결 방법: 클라이언트의 프로토콜 유형, Base URL, 모델이 모두 일치하도록 설정하세요. OpenAI 호환 형식을 쓴다면 OpenAI 유형의 제공업체를 선택하고, Claude Code 같은 네이티브 도구는 Anthropic 프로토콜에 맞게 설정하세요. Gemini 네이티브 기능이 필요하다면 Gemini 형식으로 설정하세요. APIYI는 OpenAI 호환 형식과 Claude, Gemini 등의 네이티브 API 형식을 모두 지원해요. 각 네이티브 형식의 접속 주소는 기억에 의존해 경로를 조합하지 말고 docs.apiyi.com 문서에서 확인하세요.
점검 항목 4: 인증 헤더가 프로토콜과 일치하는지 확인
증상: 401 오류가 발생하지만 같은 Key가 curl에서는 정상적으로 작동해요.
원인: OpenAI 호환 API는 보통 Authorization: Bearer <Key>를 사용하고, Anthropic 네이티브 API는 x-api-key와 anthropic-version을 사용해요. 일부 플랫폼은 조직이나 프로젝트 관련 요청 헤더도 요구해요. curl에서는 올바른 헤더를 썼지만 클라이언트가 다른 프로토콜의 헤더를 전송했거나, 게이트웨이가 인식하지 못하는 조직 헤더를 포함해 인증에 실패했을 수 있어요.
확인 방법: curl과 클라이언트 로그의 요청 헤더를 비교하고, 특히 Authorization, x-api-key, Content-Type, OpenAI-Beta 등의 필드를 살펴보세요. Key 앞뒤에 불필요한 공백, 줄바꿈 또는 따옴표가 있는지도 확인하세요. 웹페이지에서 복사해 붙여넣을 때 흔히 생기는 문제예요.
해결 방법: 인증 헤더는 프로토콜에 맞춰야 해요. 프로토콜을 올바르게 선택하면 대부분의 클라이언트가 적절한 헤더를 자동으로 전송해요. 클라이언트에서 요청 헤더를 직접 설정할 수 있다면 불필요한 조직 또는 프로젝트 헤더를 삭제하세요. Key도 다시 붙여넣고 불필요한 문자가 없는지 확인하세요.
API 중계 서비스 점검 항목 5~7: 모델 ID, 요청 본문, 네트워크 스트리밍
점검 항목 5: 모델 ID와 모델 매핑
증상: 404 또는 400 오류와 함께 모델이 존재하지 않거나 유효하지 않다는 메시지가 표시돼요. 또는 다른 모델은 정상인데 특정 모델만 실패해요.
원인: 모델 ID는 게이트웨이의 모델 목록과 한 글자도 다르지 않아야 해요. 대소문자, 버전 접미사, 접두사 표기 방식(예: provider/model 형식), 별칭 등이 다를 수 있어요. 같은 모델이라도 플랫폼마다 이름이 다를 수 있고, 클라이언트의 내장 모델 목록에 원하는 ID가 없어 기본값으로 자동 변경되기도 해요.
확인 방법: 게이트웨이의 모델 목록 API 또는 콘솔에서 모델 ID를 복사해 클라이언트 로그의 요청 본문에 있는 model 필드와 한 글자씩 비교하세요. 특정 모델만 실패한다면 먼저 모델 ID와 엔드포인트가 일치하는지 확인하고, 계정에 해당 모델을 사용할 권한이 있는지도 살펴보세요.
해결 방법: 클라이언트에 사용자 지정 모델을 직접 추가하고 게이트웨이에서 제공한 ID를 입력하지 말고 그대로 붙여넣으세요. 클라이언트에서 모델 매핑을 수행한다면 매핑 후 이름도 정확한지 확인하세요.
💡 모델 ID 사용 팁: APIYI apiyi.com에서 하나의 키로 OpenAI, Claude, Gemini, DeepSeek, Qwen 등 여러 회사의 모델을 호출할 때는 콘솔의 모델 목록에 표시된 ID를 사용하세요. 같은 모델도 플랫폼마다 이름이 다를 수 있으므로 콘솔에서 복사하는 것이 가장 간편하고 안전해요. 모델 사용 가능 여부도 콘솔과 문서를 기준으로 확인하세요.
체크포인트 6: 요청 본문과 멀티모달 형식
증상: 텍스트 대화는 정상인데, 이미지를 보내거나 도구를 호출하거나 추론 파라미터를 켜면 400 오류가 발생해요.
원인: 요청 본문 호환성 문제는 주로 멀티모달 content 배열의 구조, image_url 필드 형식, base64 이미지의 data:image/png;base64, 같은 MIME 접두사 누락에서 발생해요. 도구 호출 필드가 현재 프로토콜에 맞지 않을 수도 있어요. 모델에 따라 max_tokens와 max_completion_tokens의 요구사항도 다르고, reasoning 관련 파라미터는 일부 모델에서만 지원해요. 공급업체마다 파라미터가 완전히 호환되는 것은 아니에요.
확인 방법: 변수를 하나씩 추가해 보세요. 먼저 텍스트만 전송하고, 성공하면 스트리밍을 켜고, 이어서 도구 호출과 멀티모달 기능을 차례로 추가해요. 매 단계마다 테스트하면 어느 필드에서 문제가 시작되는지 찾을 수 있어요. 오류 메시지에 구체적인 필드가 표시되는 경우가 많으니 전체 오류 응답을 확인하세요.
해결 방법: 클라이언트에서 필요 없는 고급 파라미터를 끄고, 대상 모델의 문서에 맞게 필드를 수정하세요. 이미지는 올바른 base64 접두사나 접근 가능한 URL을 사용하고, 도구 정의는 현재 프로토콜의 형식에 맞게 작성하세요.
체크포인트 7: 네트워크, 프록시, TLS와 스트리밍 버퍼링
증상: 연결 시간이 초과되거나, stream disconnected 오류가 발생하거나, 오랫동안 응답이 없다가 빈 응답이 돌아와요. 비스트리밍은 정상인데 스트리밍만 실패하기도 해요.
원인: 클라이언트는 시스템 프록시나 환경 변수에 설정된 프록시를 사용하는데 curl은 사용하지 않을 수 있고, 그 반대일 수도 있어요. 기업 방화벽, TLS 인증서 검증, IPv6 주소 해석, DNS 때문에 클라이언트가 연결되지 않을 수도 있어요. 스트리밍 시 일부 프록시는 응답을 버퍼링해 전체 콘텐츠가 도착한 뒤에야 전달해요. 그러면 클라이언트는 데이터를 기다리다 시간 초과나 스트림 단절로 판단할 수 있어요.
확인 방법: 먼저 ‘연결이 수립되지 않은 경우’와 ‘스트림이 중간에 끊긴 경우’를 구분하세요. 전자는 TLS 또는 연결 오류가 있는지 확인하고, 후자는 보통 일부 콘텐츠를 이미 받은 상태예요. 스트리밍을 끄고 다시 시도해 비스트리밍이 정상이면 프록시 버퍼링이나 시간 초과 설정을 의심할 수 있어요. 클라이언트와 터미널의 프록시 환경 변수가 일치하는지도 확인하세요.
해결 방법: 클라이언트와 curl의 프록시 설정을 통일하고, 스트리밍 요청은 응답을 버퍼링하는 프록시를 거치지 않도록 설정하세요. 클라이언트의 시간 초과 시간도 적절히 늘려 보세요. 업스트림 연결이 간헐적으로 끊긴다면 제한된 횟수만큼 재시도하거나, 일시적으로 다른 모델로 전환해 특정 업스트림만의 문제인지 확인할 수 있어요.
API 중계 서비스 빠른 시작: 오류 코드 대조표와 클라이언트 설정 체크리스트
오류가 발생하면 먼저 오류 코드로 원인 범위를 좁힌 뒤, 설정 체크리스트를 하나씩 확인하세요.
오류 코드 대조표
| 오류 코드 | 흔한 원인 | 우선 확인할 항목 |
|---|---|---|
| 401 | API 키가 유효하지 않거나 만료 또는 비활성화됨; 요청 헤더 형식 오류; 조직 또는 프로젝트 불일치 | 확인 항목 1, 4 |
| 403 | API 키는 유효하지만 모델, 조직 또는 지역 정책에 의해 거부됨; IP 허용 목록; 모델 미개통 | 확인 항목 5, 계정 권한 |
| 404 | Base URL 경로 오류; 엔드포인트 또는 모델 ID가 존재하지 않음; 게이트웨이가 해당 라우트를 지원하지 않음 | 확인 항목 2, 3, 5 |
| 400 | 요청 본문, 파라미터, 모델 ID 또는 멀티모달 필드가 유효하지 않음; 제공업체 파라미터 호환성 문제 | 확인 항목 5, 6 |
| 429 | 요청 속도 제한 또는 사용 한도 부족 | Retry-After를 확인하고, 재시도 간격을 늘리거나 모델 변경 |
| 500/502/503/529 | 업스트림 또는 게이트웨이 오류. 529는 과부하 시 자주 발생 | 횟수를 제한해 재시도하고 게이트웨이 로그 확인 |
| 타임아웃, stream disconnected | 네트워크, 프록시, TLS 또는 업스트림 연결 중단 | 확인 항목 7 |
클라이언트 설정 체크리스트
| 확인 항목 | 확인할 내용 |
|---|---|
| 설정 출처 | 환경 변수, 설정 파일, GUI 중 어디를 수정했나요? 어느 쪽의 우선순위가 가장 높은가요? 여러 profile이나 프로젝트 설정이 서로 덮어쓰고 있나요? |
| Base URL | /v1이 포함되어 있나요? 클라이언트가 /v1을 자동으로 추가하나요? 끝에 불필요한 슬래시가 있나요? |
| 엔드포인트 유형 | Chat Completions, Responses, Claude 또는 Gemini 네이티브 중 무엇인가요? 클라이언트 버전이 이를 지원하나요? |
| 인증 헤더 | Authorization: Bearer와 x-api-key 중 무엇을 사용하나요? anthropic-version이 필요한가요? |
| 모델 ID | 대소문자와 접두사를 포함해 게이트웨이의 모델 목록과 정확히 일치하나요? |
| 요청 본문 | 도구, 이미지, reasoning 파라미터가 포함되어 있나요? max_tokens 필드가 대상 모델에 맞나요? |
| 스트리밍과 네트워크 | 스트리밍이 활성화되어 있나요? 프록시가 버퍼링하나요? 클라이언트와 curl의 프록시 설정이 일치하나요? |
최소 요청으로 비교 재현하기
가장 효과적인 방법은 변수를 통제해 비교하는 거예요. 동일한 Base URL, API 키, 모델, 요청 본문을 사용해 먼저 curl로 요청하고, 이어서 클라이언트로 요청하세요. 구체적인 단계는 다음과 같아요.
- 모델 목록 API로 API 키와 Base URL을 확인하세요. 예를 들어
https://api.apiyi.com/v1/models에 요청을 보내세요. - 최소한의 일반 텍스트 chat 요청으로 엔드포인트와 모델 ID를 확인하세요.
- 스트리밍을 켜고 네트워크와 프록시를 확인하세요.
- 도구 호출이나 멀티모달 기능을 추가해 요청 본문을 확인하세요.
- 각 단계에서 클라이언트 로그와 게이트웨이 측 로그를 함께 확인하세요.
🚀 문제 해결 팁: APIYI 콘솔에서 사용 통계와 상세 호출 로그를 확인할 수 있어요. 클라이언트에 오류가 났는데 콘솔에 호출 기록이 없다면 요청이 게이트웨이에 도달하지 않은 것이므로 클라이언트 설정이나 로컬 네트워크를 확인하세요. 오류 정보가 포함된 기록이 있다면 로그를 보고 파라미터 문제인지 업스트림 문제인지 판단할 수 있어요.
자주 묻는 질문 FAQ
Q1: curl은 되는데 클라이언트가 연결되지 않을 때, Key를 바꾸면 해결되나요?
대개는 도움이 되지 않아요. curl이 성공했다면 Key가 유효하다는 뜻이에요. “Key를 바꿔서 해결된” 경우는 교체 과정에서 클라이언트를 재시작하거나 프로필을 바꿔 설정이 다시 로드된 경우가 많아요. Key를 바꾸기보다 클라이언트를 완전히 종료하고 재시작한 뒤, 로그에서 실제 사용한 Base URL과 Key를 확인하세요. APIYI 콘솔에서 Key 상태와 호출 기록을 확인해 실제로 Key에 문제가 있는지도 살펴볼 수 있어요.
Q2: /models 엔드포인트는 되는데 왜 chat 요청은 실패하나요?
모델 목록 엔드포인트는 인증과 Base URL이 기본적으로 올바른지만 확인해요. chat 엔드포인트, 모델 ID, 요청 본문은 검증하지 않아요. chat 요청이 실패하면 클라이언트 프로토콜이 엔드포인트와 일치하는지(확인 항목 3), 모델 ID가 목록과 한 글자까지 일치하는지(확인 항목 5), 요청 본문에 해당 모델이 지원하지 않는 파라미터가 있는지(확인 항목 6) 순서대로 확인하세요.
Q4: 특정 모델만 실패하고 다른 모델은 모두 정상이라면 무엇부터 확인해야 하나요?
먼저 모델 ID와 엔드포인트를 확인하고, 그다음 계정 권한을 살펴보세요. 가장 흔한 원인은 모델 ID의 대소문자, 접두사, 별칭 차이예요. 해당 모델에 네이티브 형식처럼 다른 프로토콜이 필요한지도 확인하세요. 마지막으로 권한이나 사용 가능 여부를 점검하면 돼요. APIYI에서는 Key 하나로 여러 제공사의 모델을 전환할 수 있으므로, 비슷한 모델로 바꿔 테스트하면 특정 모델의 문제인지 전체 설정의 문제인지 빠르게 구분할 수 있어요.
Q5: 클라이언트 문제인지 게이트웨이 문제인지 어떻게 구분하나요?
핵심은 게이트웨이가 요청을 받았는지, 동일한 요청을 curl로 보냈을 때 성공하는지 확인하는 거예요. 게이트웨이에 기록이 없다면 대체로 클라이언트나 로컬 네트워크 문제예요. 동일한 요청이 curl에서는 성공하고 클라이언트에서는 실패한다면 URL 조합이나 요청 본문 문제일 가능성이 커요. curl에서도 실패하고 로그에 5xx가 표시된다면 게이트웨이 지원팀에 문의하세요.
정리: API 중계 서비스 10분 점검 체크리스트와 도움을 요청할 시점
“curl은 되는데 클라이언트는 연결되지 않는” 문제가 생겼다면 서둘러 Key를 바꾸지 말고, 아래 체크리스트를 10분 동안 살펴보세요.
- 클라이언트 로그 확인: 실제 요청의 URL, 요청 헤더와 요청 본문을 확인해 설정이 적용됐는지 살펴보세요.
- Base URL 확인:
/v1이 한 번만 나타나는지, 이중 슬래시나 중복된 경로 구간은 없는지 확인하세요. - 엔드포인트 프로토콜 확인: Chat Completions, Responses, Claude Messages, Gemini 네이티브 중 클라이언트 유형에 맞는지 확인하세요.
- 인증 헤더 확인:
Authorization: Bearer또는x-api-key를 확인하고, 불필요한 조직 헤더와 Key 앞뒤의 공백을 제거하세요. - 모델 ID 확인: 게이트웨이 모델 목록과 한 글자씩 비교하세요.
- 최소 요청 전송: 같은 Key, 같은 모델, 같은 요청 본문으로 curl과 클라이언트에서 각각 요청해 비교하세요.
- 스트리밍 추가: 실패하면 프록시 버퍼링과 타임아웃을 확인하세요.
- 도구 또는 멀티모달 추가: 실패하면 요청 본문의 필드를 확인하세요.
- 최종 판단: 게이트웨이 로그를 바탕으로 클라이언트 문제인지 게이트웨이 문제인지 판단하세요.
언제 클라이언트 버그일까요? 게이트웨이에 호출 기록이 없거나, 완전히 동일한 URL과 요청 헤더, 요청 본문으로 curl은 성공하지만 클라이언트는 실패하는 경우예요. 설정이 올바르고 현재 버전이 해당 엔드포인트를 지원하는 것도 확인했다면, 클라이언트를 업그레이드하거나 해당 프로젝트에 문제를 제보하세요.
언제 게이트웨이 지원팀에 문의해야 할까요? 동일한 최소 요청이 curl에서도 실패하고 게이트웨이 로그에 호출 기록과 5xx 응답이 남는 경우예요. 또는 특정 모델에서 오류가 계속 발생하지만 다른 모델은 정상 작동하고, 모델 ID와 권한 문제도 아닌 경우가 해당해요. 문의할 때 요청 시각, 모델 ID, 오류 코드와 로그의 오류 메시지를 함께 전달하면 원인을 더 빨리 찾을 수 있어요.
안정성이 중요한 팀 도구에서는 여러 모델과 경로를 확보하는 것 자체가 문제 해결 수단이에요. 한 모델이나 경로에 문제가 생겼을 때 다른 모델로 전환해 비교 테스트하면 문제 범위를 바로 파악할 수 있어요. APIYI apiyi.com에서는 하나의 Key로 OpenAI 호환 형식과 Claude, Gemini 네이티브 형식에 접근하고, 콘솔의 사용량과 로그를 통해 빠르게 확인할 수 있어요. 가격과 이용 가능 여부는 콘솔과 문서를 참고하세요.
작성자: APIYI 기술팀
기술 교류: APIYI 웹사이트 첫 화면에서 문의해 주세요
