문제 해결

증상부터 시작해 해결 방법을 따르세요. 대부분의 실패는 base URL, key, 모델 ID, 잔액에서 비롯됩니다.

증상별 표

인증

폐기된 key는 key prefix를 포함한 메시지를 반환합니다.

{
  "status": 401,
  "code": "UNAUTHORIZED",
  "message": "API Key has been revoked (keyPrefix=...)"
}

체크리스트:

• Model API와 Felo APIs의 헤더는 Authorization: Bearer <key>입니다.
• Data API는 X-API-Key: <key>도 받습니다.
• key가 따옴표로 감싸지지 않았고, 환경 변수를 복사할 때 생긴 줄바꿈이 없어야 합니다.
• 배포 환경에 실제로 변수가 설정되어 있어야 합니다. 로컬에서 동작하는 key가 프로덕션에는 없을 수 있습니다.
• key가 삭제되거나 교체되지 않았어야 합니다. 삭제되거나 교체된 key는 다시 볼 수 없으니 새로 만드세요.

key 생성과 제한은 인증을 참고하세요.

Base URL 함정

흔한 실수 두 가지:

1. SDK가 이미 확장하는 base URL에 /chat/completions를 추가하는 것.
2. Anthropic base URL을 https://openapi.felo.ai/api/v1로 설정하는 것. SDK가 /v1/messages를 붙여 요청이 /api/v1/v1/messages가 됩니다.

모델 ID 문제

모델 ID는 카탈로그의 공개 ID이며, 업스트림 공급자의 내부 이름이나 표시 이름이 아닙니다.

• ID는 모델 페이지 또는 GET /api/v1/models에서 확인하세요.
• 모델이 호출하는 프로토콜을 지원하는지(supported_protocols) 확인하세요.
• 채널을 고정했다면 해당 채널이 그 모델에 대해 공개되어 있고 실행 가능한지 확인하세요. 사용할 수 없는 채널은 fallback이 아닙니다.

채널 및 공급자 라우팅을 참고하세요.

스트리밍 문제

• stream: true는 query 파라미터가 아니라 요청 본문에 설정하세요.
• 응답 본문을 스트림으로 읽으세요. 전체 응답을 기다리면 스트리밍의 의미가 없습니다.
• 일부 프록시와 서버리스 플랫폼은 응답을 버퍼링합니다. 요청을 중계하는 라우트에서 버퍼링을 끄세요.
• Chat Completions는 choices[0].message가 아니라 choices[0].delta를 스트리밍합니다. 최종 내용은 여러 chunk에 나뉘어 도착합니다.
• 연결이 끊기면 깔끔한 종료 이벤트 없이 스트림이 끝날 수 있습니다. 끊긴 연결은 불완전한 응답으로 취급하세요.

비동기 작업 문제

• 작업 계열에 맞는 상태 endpoint를 폴링하세요. Felo 워크플로는 GET /v2/tasks/{task_id}/status, 모델의 비디오·이미지 작업은 각자의 생성 endpoint를 사용합니다.
• 성공뿐 아니라 실패와 만료를 포함한 모든 종료 상태에서 멈추세요.
• 비디오 및 이미지 callback은 현재 무시됩니다. webhook을 기다리지 마세요.
• 결과 URL은 수명이 짧을 수 있습니다. 다운로드가 만료되면 상태 endpoint에서 새 URL을 받으세요.
• 다시 제출하기 전에 작업을 확인하세요. 실행 중인 작업을 다시 제출하면 중복이 생기고 둘 다 청구됩니다.

비동기 작업을 참고하세요.

Data API 문제

• Data API 참조의 정확한 method 경로를 유지하세요.
• 요청 본문은 공급자별입니다. 한 공급자에서 동작하는 필드가 다른 공급자에서도 동작한다고 보장되지 않습니다.
• 공급자 오류는 공급자별 메시지를 담은 4xx 응답으로 올 수 있습니다. request_id와 응답 본문을 기록하세요.

보안 알림

• API key를 브라우저 코드, 모바일 앱 번들, 공개 저장소에 넣지 마세요. 서버에 두고 요청을 프록시하세요.
• 전체 key를 기록하지 마세요. 식별이 필요하면 prefix만 기록하세요.
• 유출 가능성이 있으면 즉시 key를 교체하세요.

지원팀에 문의하기 전에

다음을 모으세요.

1. endpoint와 HTTP method.
2. HTTP 상태, code, request_id.
3. 모델 ID 또는 작업 ID.
4. 시간대가 포함된 타임스탬프.
5. 비밀 정보를 제거한 최소 요청 본문.

계정 email과 함께 지원팀에 보내세요. 전체 API key는 포함하지 마세요.

관련 문서

• 오류, 속도 제한 및 재시도
• 프로토콜 및 SDK
• 결제 및 크레딧
• 인증