가이드

오류, 속도 제한 및 재시도

오류 응답과 속도 제한 헤더를 읽고 안전하게 재시도하며 일반적인 장애를 진단하세요.

모든 Felo API는 안정적인 오류 코드와 request ID가 담긴 JSON 오류 본문을 반환합니다. 먼저 HTTP 상태, 그다음 code, 마지막으로 message를 읽으세요.

오류 envelope

현재 프로덕션 응답은 HTTP 상태를 status로 사용합니다.

{
  "status": 401,
  "code": "UNAUTHORIZED",
  "message": "Invalid API Key",
  "request_id": "202610221444486982113280416060637185"
}

일부 오래된 endpoint 예시는 status: "error"와 다른 code 문자열을 사용합니다. message의 정확한 표현이 아니라 HTTP 상태와 code를 기준으로 분기하세요.

HTTP	Code	의미	해야 할 일
400	Endpoint별 검증 코드	파라미터가 없거나 잘못됨	요청을 수정하세요. 그대로 재시도하지 마세요
401	`UNAUTHORIZED`	API key가 없거나, 잘못되었거나, 만료되었거나, 폐기됨	`Authorization: Bearer $FELO_API_KEY`를 보내세요. 폐기되었다면 key를 교체하세요
402	`INSUFFICIENT_CREDITS`	서비스 크레딧 부족	Console Billing에서 충전한 뒤 재시도하세요
404	Endpoint별	알 수 없는 모델, 작업, 라우트	모델 ID 또는 작업 ID와 endpoint 경로를 확인하세요
429	`RATE_LIMITED`	속도 제한을 초과함	`Retry-After`를 기다린 뒤 재시도하세요
5xx	`CHAT_FAILED`, `*_FAILED`, `SERVICE_UNAVAILABLE`	업스트림 또는 서비스 장애	backoff와 함께 재시도하세요. 계속되면 지원팀에 문의하세요

Endpoint 참조 문서에는 해당 endpoint 고유의 코드가 나열되어 있습니다. Chat API 오류 또는 호출하는 endpoint의 참조부터 확인하세요.

Felo 오류 본문에는 request_id가 포함됩니다. endpoint, HTTP 상태, 오류 코드, 모델 ID, 작업 ID와 함께 기록하세요. 전체 API key는 절대 기록하지 마세요.

Model API는 선택적 X-Request-Id 요청 헤더도 받습니다. 보내면 진단을 위해 응답에 그대로 돌아오므로 자기 로그와 요청을 연결할 수 있습니다. 보내지 않았다면 반환된 request_id를 사용하세요.

/v2/chat은 문서화된 강제 속도 제한이 있는 유일한 Felo endpoint입니다.

유효한 유료 Felo 구독(엔터프라이즈 포함) 사용자는 면제되며 X-RateLimit-* 헤더를 받지 않습니다. 구독 상태를 확인할 수 없으면 제한이 그대로 적용됩니다.

다른 /v2/** endpoint에는 현재 강제 속도 제한이 없습니다. Model API 요청은 업스트림 공급자의 제한을 받아 429로 나타날 수 있습니다.

숫자 한도를 하드코딩하지 마세요. 각 응답의 헤더를 읽으세요.

상황	재시도?
400, 401, 402, 404	아니요. 먼저 요청, key, 잔액을 고치세요.
429	예. `Retry-After` 또는 `X-RateLimit-Reset` 이후에.
5xx, 타임아웃, 연결 재설정	예. 지수 backoff와 jitter를 사용하세요.
스트리밍 연결이 응답 중간에 끊김	애플리케이션이 중복 생성을 감당할 수 있을 때만 재시도하세요.

권장 루프: