계정

문제 해결

401, 402, 403, 404, 429 오류와 잘못된 base URL, 타임아웃, 끊기는 스트리밍, CORS, SDK 버전 문제를 원인별로 진단하고 해결하는 순서를 오류 코드별 항목으로 안내합니다. 증상별로 확인할 항목을 따라가면 됩니다.

대부분의 문제는 HTTP 상태 코드와 오류 본문의 code로 나타납니다. 아래에서 해당 코드를 찾아보세요. 전체 목록은 오류에 있습니다. 실패한 요청(모든 4xx 또는 5xx)에는 요금이 부과되지 않습니다.

{ "error": { "message": "...", "type": "authentication_error", "code": "invalid_api_key" } }

401 `invalid_api_key`

키가 없거나, 형식이 잘못되었거나, 폐기된 경우입니다.

Authorization: Bearer sk-api14-... 형태로 보내세요. OpenAI SDK는 apiKey / api_key로 이를 자동 처리합니다. curl을 쓴다면 실행하는 셸에 $API14_API_KEY가 실제로 설정되어 있는지 확인하세요(echo ${API14_API_KEY:0:9}가 sk-api14-를 출력해야 합니다).
키를 .env 파일에서 읽을 때 불필요한 따옴표나 줄바꿈이 섞이지 않았는지 확인하세요.
환경에 남아 있는 OPENAI_API_KEY가 의도한 키를 덮어쓸 수 있습니다. 키를 명시적으로 전달해 이 가능성을 배제하세요.
폐기된 키는 즉시 실패합니다. 키는 한 번만 표시되므로 잃어버렸다면 API 키에서 새 키를 만들고 이전 키를 폐기하세요.

인증을 참고하세요.

402 `insufficient_balance`

USD 잔액이 $0이거나 (동영상의 경우) 작업의 예상 비용보다 적습니다. 자금을 추가할 때까지 요청이 차단되며, 재시도해도 해결되지 않습니다.

GET /credits 또는 결제에서 잔액을 확인하세요. 잔액 및 키 정보를 참고하세요.
자금을 추가하거나 자동 충전을 켜세요. 요금제는 매달 포함된 사용량을 같은 잔액에 추가합니다. 요금 및 결제를 참고하세요.
장시간 실행되는 작업에서는 이 코드를 치명적 오류로 취급해 중단하세요. SDK의 재시도가 계속 돌게 두면 안 됩니다.

403 `model_not_allowed` 또는 `plan_required`

model_not_allowed: 키에 모델 허용 목록이 있는데 이 모델 id가 포함되어 있지 않습니다. API 키에서 키의 허용 목록을 수정하거나 목록이 없는 키를 사용하세요. 변형 접미사도 포함해서 판단하므로, 보내는 정확한 id가 허용되어 있는지 확인하세요.
plan_required: 현재 요금제에 이 모델 카테고리가 포함되어 있지 않습니다. 기본 요금제는 모든 카테고리를 제공합니다. 요금 페이지에서 요금제를 확인하세요.

404 `model_not_found` 또는 `not_found`

model_not_found: 모델 id를 알 수 없거나, 비활성화되었거나, 제거되었습니다. id에는 제공자 접두사가 포함됩니다. gpt-5-mini가 아니라 openai/gpt-5-mini입니다. 정확한 id는 GET /models 또는 GET /models/{id}로 조회하세요(키 불필요). 모델 id 및 변형을 참고하세요.
not_found: 경로가 존재하지 않거나, 동영상 작업 또는 generation id가 본인의 것이 아닙니다. 대개 base URL이 잘못된 경우입니다(아래 참고). 요청 직후 Generation 조회를 하면 기록이 나타나기 전 몇 초 동안 404가 반환될 수도 있습니다.

잘못된 base URL

base URL은 정확히 다음과 같습니다.

https://api14.com/api/v1

흔한 실수는 다음과 같습니다.

설정한 값	결과
`https://api14.com/v1` 또는 `https://api14.com`	요청이 API가 아닌 웹사이트로 전달됩니다. HTML 응답, 404, 또는 브라우저의 CORS 오류가 발생합니다.
base로 `https://api14.com/api/v1/chat/completions`	SDK가 경로를 한 번 더 붙입니다. base만 설정하세요.
`https://api.openai.com/v1` (기본값)	api14 키가 OpenAI에서 거부됩니다. 코드에서 또는 `OPENAI_BASE_URL`로 base URL을 설정하세요.

라이브러리별 특이사항: ruby-openai는 v1을 스스로 붙이므로 uri_base는 https://api14.com/api입니다(Ruby). openai-go는 끝에 슬래시가 필요하여 https://api14.com/api/v1/을 사용합니다(Go).

429 `rate_limited`

키 또는 요금제의 분당 요청 수 제한(Free 5, Pro 100, Team 3,000, Enterprise 3,000+)을 초과했습니다. 응답에는 Retry-After: 60이 포함됩니다.

Retry-After만큼 기다린 뒤 지수 백오프와 지터를 적용해 재시도하세요. 공식 OpenAI SDK는 이미 이렇게 동작합니다(기본 두 번 재시도하며 maxRetries / max_retries로 늘릴 수 있습니다).
대량 작업에서는 요청을 한꺼번에 보내지 말고 속도를 조절하며, 한 요청에 여러 항목을 담으세요. 가이드: 배치 처리를 참고하세요.
429는 업스트림 제공자에서 올 수도 있으며, 특히 :free 변형에서 그렇습니다. 모델 폴백 또는 제공자 라우팅으로 부하를 분산하세요.

429 `daily_limit_reached`

키가 일일 USD 지출 한도에 도달했습니다. 다음 UTC 날짜가 될 때까지는 재시도해도 소용없습니다. 트래픽이 예상된 것이라면 API 키에서 한도를 올리거나 제거하세요. 재시도 로직이 이 코드를 rate_limited와 구분하는지 확인하세요. 그렇지 않으면 작업이 아무 의미 없이 계속 재시도됩니다. 속도 제한을 참고하세요.

타임아웃

대형 모델, 추론 모델, 긴 출력은 몇 분이 걸릴 수 있습니다.

클라이언트 타임아웃을 확인하세요. Node와 Python SDK의 기본값은 10분이며, 다른 HTTP 클라이언트는 더 짧은 기본값을 쓰는 경우가 많습니다.
긴 생성은 스트리밍하세요. 토큰이 몇 초 안에 도착하기 시작하고, 프록시와 로드 밸런서의 유휴 연결 타임아웃이 문제가 되지 않습니다. 스트리밍을 참고하세요.
max_tokens를 설정하고, 추론 모델에서는 reasoning effort를 낮추세요.
자체 서버를 통해 요청을 중계한다면 그 서버의 프록시 타임아웃(예: 기본값이 60초인 nginx proxy_read_timeout)도 적용됩니다.
클라이언트 쪽 타임아웃이 업스트림 생성을 취소하지는 않으며, 해당 생성은 여전히 청구될 수 있습니다. 요청 id로 Generation 조회를 사용해 확인하세요.

스트리밍이 끊기거나 일찍 멈출 때

마지막 청크의 finish_reason을 확인하세요. "length"는 max_tokens에 도달했다는 뜻이고, "error"는 스트림 도중 제공자가 실패했다는 뜻이며 해당 청크에 error 객체가 담겨 있습니다. 재시도하거나 폴백을 추가하세요.
프록시와 서버리스 플랫폼이 SSE 응답을 버퍼링하거나 끊는 경우가 있습니다. 버퍼링을 끄고(nginx에서는 X-Accel-Buffering: no) 플랫폼의 최대 응답 시간을 확인하세요.
스트림을 직접 파싱한다면 :로 시작하는 주석 줄(keep-alive)은 무시하고 data: [DONE]에서 멈추세요.
연결을 일찍 닫아도 청구가 취소되지는 않습니다. 제공자가 어쨌든 생성을 끝낼 수 있습니다.

CORS 오류와 브라우저 앱

API 키를 브라우저나 모바일 코드에 절대 넣지 마세요. 누구나 페이지에서 키를 읽어 잔액을 쓸 수 있습니다. api14는 자체 백엔드에서 호출하고 브라우저에는 자체 엔드포인트만 노출하세요.

// server.js (Node / Express)
app.post("/api/chat", async (req, res) => {
  const stream = await client.chat.completions.create({
    model: "openai/gpt-5-mini",
    messages: req.body.messages, // 이 입력을 검증하고 제한하세요
    stream: true,
  });
  for await (const chunk of stream) res.write(chunk.choices[0]?.delta?.content ?? "");
  res.end();
});

개발 중 브라우저에서 나는 CORS 오류는 대개 base URL이 잘못되었거나(요청이 API가 아닌 웹사이트에 도달함), API의 preflight가 허용하지 않는 커스텀 요청 헤더 때문입니다. 호출을 서버로 옮기면 둘 다 해결됩니다.

SDK 버전 문제

openai 1.0 미만의 Python은 openai.ChatCompletion.create와 openai.api_base를 사용합니다. pip install -U openai로 업그레이드하고 OpenAI(base_url=..., api_key=...) 클라이언트를 사용하세요.
chat.completions.parse가 없는 경우: 오래된 1.x/4.x 릴리스에는 client.beta.chat.completions.parse만 있습니다. 패키지를 업그레이드하세요.
게이트웨이 필드(provider, models, reasoning, plugins)에 대해 SDK가 알 수 없는 파라미터 오류를 내는 경우: Python에서는 extra_body로, 다른 SDK에서는 이에 해당하는 extra-body 옵션으로 전달하세요. OpenAI SDK 호환성을 참고하세요.
제공자 메시지가 담긴 업스트림 400: 해당 모델이나 제공자가 지원하지 않는 파라미터입니다. 모델에서 모델의 supported_parameters를 확인하거나 provider: { "require_parameters": true }를 추가하세요.

문제 해결

401 invalid_api_key

402 insufficient_balance

403 model_not_allowed 또는 plan_required

404 model_not_found 또는 not_found