버그를 보고하기 전에

무언가가 작동하지 않을 때, 문제가 내 쪽인지 우리 쪽인지 가장 빠르게 확인하는 방법은 다른 도구에서 동일한 요청을 실행해 보는 것입니다.

"API가 고장났다"는 보고의 약 10건 중 9건은 잘못 설정된 base URL, 만료된 API 키, 잘못된 모델 이름, 또는 세 버전 전 SDK 기준의 튜토리얼에서 가져온 요청 바디 형식으로 판명됩니다.

빠른 자가 테스트

이 curl 명령어를 터미널에 복사하세요. YOUR_KEY를 Dashboard의 API 키로 교체한 후 실행하세요. 정상적인 응답이 돌아온다면, API 키·네트워크·백엔드 모두 정상입니다 — 문제가 있다면 클라이언트 코드나 환경에 있는 것입니다.

cURL

curl https://api.airforce/v1/chat/completions \
  -H "Authorization: Bearer sk-air-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1-mini",
    "messages": [{"role": "user", "content": "ping"}]
  }'

단계별 체크리스트

API 키가 유효한가요?

Dashboard → API Keys를 열고 키가 코드에서 사용하는 값과 일치하는지 확인하세요. 복사-붙여넣기 시 "sk-air-" 접두사 앞에 공백이 들어가는 경우가 흔한 함정입니다.

증상: 401 Unauthorized.

base URL이 올바른가요?

base URL은 반드시 https://api.airforce/v1이어야 합니다 — http가 아닌 https이며, /v1 접미사도 필수입니다. OpenAI의 v1 경로 이전 시대의 튜토리얼은 이를 생략하기도 합니다.

증상: 404 Not Found, 또는 curl이 응답 없이 멈춤.

모델 이름의 철자가 정확한가요?

모델 ID는 대소문자를 구분합니다. Models 페이지를 방문하거나 GET /v1/models를 호출해 정확한 ID를 확인하세요. 오타나 지원이 중단된 모델은 "동작하지만 잘못됨"이 아닌 명확한 오류를 반환합니다.

증상: 400 unknown_model 또는 404 model_not_found.

요청 바디의 형식이 올바른가요?

채팅 완성에는 messages 배열을 사용합니다. 이미지에는 prompt + n을, 오디오 TTS에는 input + voice를 사용합니다. 채팅 형식의 바디를 /v1/images/generations에 보내면 400이 반환됩니다 — 문서 간 코드 조각을 복사할 때 놓치기 쉽습니다.

증상: 응답 바디에 해당 필드 이름이 명시된 400.

속도 제한이나 할당량 한도에 도달했나요?

429 = 이 분에 너무 많은 요청. 402 = 플랜 또는 잔액 소진. 둘 다 Dashboard에서 확인할 수 있습니다. 무료 티어 요청과 유료 플랜 요청의 한도는 별도로 관리되므로, 유료 모델은 정상 응답하는 동안 무료 모델에서 속도 제한이 걸릴 수 있습니다.

증상: 429 Too Many Requests 또는 402 Payment Required.

모델이 현재 정상 운영 중인가요?

Models 페이지에서 공급자 장애 여부를 확인하세요 — "degraded" 또는 "major outage"로 표시됩니다. 특정 모델만 다운되고 다른 모델은 작동한다면, 우리가 우회 처리하는 공급자 측 문제이며 클라이언트 오류가 아닙니다.

증상: 특정 모델에서 5xx가 반환되는 반면 다른 모델은 정상 작동.

HTTP 상태 코드의 의미

모든 오류 응답에는 표준 HTTP 상태 코드가 포함됩니다. 각 코드의 의미를 알면 불필요한 티켓을 줄일 수 있습니다.

실제 버그인 경우

위의 curl 자가 테스트는 성공하지만 코드에서 동일한 요청이 실패한다면, 문제는 클라이언트(또는 사용하는 라이브러리)에 있습니다. 자가 테스트 자체가 5xx로 실패하거나, 요청 내용과 맞지 않는 메시지와 함께 4xx가 반환된다면 보고할 가치가 있습니다.

효과적으로 보고하는 방법

Dashboard에서 지원 티켓을 열거나 Discord의 #support에 게시하세요. 다음 내용을 포함하세요:

• 전체 HTTP 상태 코드와 응답 바디 (있는 경우 cf-ray 응답 헤더도 포함).
• UTC 기준 대략적인 타임스탬프.
• 모델 이름과 호출한 엔드포인트.
• 재현 가능한 최소한의 cURL (실제 API 키는 마스킹하세요!).
• 같은 키로 위의 자가 테스트가 성공하는지 여부.

Discord의 #support에 질문하기