연결 및 사용 | API 문서

호출이 실패하거나 대화가 중단되면 최소 요청으로 인증, 엔드포인트 경로 및 모델 가용성 세 가지를 먼저 확인하세요.

플랫폼에 연결할 수 없나요?

다음을 확인하세요.

API 키가 정확하고 불필요한 공백이나 줄바꿈이 없는지 확인하세요.
Base URL이 정확하고 경로가 중복되지 않는지 확인하세요.
OpenAI 클라이언트의 OpenAI 호환 경로처럼 엔드포인트가 클라이언트 프로토콜에 맞는지 확인하세요.
로컬 네트워크, 회사 프록시, 방화벽, DNS 또는 HTTPS 검사가 요청을 막는지 확인하세요.
키가 만료·삭제되었거나 제한된 계정에 속하는지 확인하세요.

OpenAI 호환 호출은 최소 비스트리밍 요청으로 테스트하세요.

bash

curl https://api.apihop.ai/openai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "messages": [
      { "role": "user", "content": "Reply with OK only." }
    ],
    "stream": false
  }'

최소 요청도 실패하면 대개 네트워크, 인증, 경로 설정, 모델 권한 또는 계정 상태 문제입니다.

모델을 선택했는데 응답이 없거나 오류가 발생하나요?

일반적인 원인:

모델 ID가 잘못되었거나 플랫폼 목록과 일치하지 않습니다.
모델이 일시적으로 제공되지 않거나 키에 허용되지 않습니다.
필드 이름, 중첩 또는 유형 오류 등으로 요청 형식이 잘못되었습니다.
잔액 부족, 너무 긴 맥락이나 출력 또는 서비스 시간 초과가 발생했습니다.
외부 클라이언트가 스트리밍이나 오류 응답을 제대로 처리하지 않습니다.

콘솔이나 모델 목록에서 정확한 ID를 복사하고 최소 본문으로 테스트한 다음 맥락과 매개변수를 점차 추가하세요.

채팅 오류나 연결 해제 시 어떻게 하나요?

실패 지점을 파악하세요.

요청 시작 전: 인증, 경로, 모델 및 매개변수를 확인하세요.
스트리밍 중: 클라이언트 시간 초과, 프록시 체인 및 SSE 파싱을 확인하세요.
긴 맥락이나 출력: 요청 크기, 출력 제한 및 서비스 시간 초과를 확인하세요.

권장 처리:

구체적인 오류 필드를 읽으세요.
잠시 비스트리밍으로 전환해 모델 실패와 스트리밍 파싱 실패를 구분하세요.
429, 불안정한 네트워크 및 일부 5xx 오류에는 백오프 재시도를 추가하세요.
서버 측 대화 상태를 가정하지 말고 재시도에 필요한 맥락을 포함하세요.
문제가 계속되면 X-Request-ID를 기록하세요.