오류 형태

{
  "error": {
    "code": "api_key_missing",
    "message": "A valid Bearer API key is required.",
    "requestId": "req_..."
  }
}

실패한 API 요청을 Rivya 지원팀이 조사해야 할 때를 대비해 로그에 requestId를 보관하세요.

안정적인 오류 코드

코드	HTTP 상태	의미	권장 조치
`public_api_disabled`	503	Public API 호출이 일시적으로 비활성화되었습니다.	나중에 다시 시도하거나 Studio에서 직접 작업하세요.
`api_key_missing`	401	요청에 Bearer API 키가 포함되지 않았습니다.	`Authorization: Bearer rvya_sk_...`를 보내세요.
`api_key_invalid`	401	API 키를 검증할 수 없습니다.	키를 확인하고 필요하면 교체하세요.
`api_key_revoked`	401	설정에서 API 키가 폐기되었습니다.	새 키를 만드세요.
`api_key_expired`	401	API 키가 더 이상 유효하지 않습니다.	새 키를 만드세요.
`api_scope_denied`	403	API 키에 필요한 권한 범위가 없습니다.	필요한 권한이 있는 키를 만드세요.
`rate_limited`	429	현재 시간 구간에 요청이 너무 많습니다.	대기 시간을 늘려 나중에 다시 시도하세요.
`validation_failed`	400	요청 본문, 모델, 프롬프트 또는 매개변수가 유효하지 않습니다.	요청 본문을 모델 참조 문서와 비교하세요.
`not_found`	404	요청한 작업이 없거나 현재 계정 소유가 아닙니다.	공개 작업 ID와 계정 소유 범위를 확인하세요.
`webhook_url_rejected`	400	웹훅 엔드포인트 URL이 허용되지 않습니다.	인증 정보, 프래그먼트, localhost 또는 사설 네트워크 주소가 없는 공개 HTTPS URL을 사용하세요.
`chat_model_not_supported`	400	선택한 모델을 Chat API에서 사용할 수 없습니다.	`/api/v1/models`에서 사용 가능한 채팅 모델을 선택하세요.
`chat_session_conflict`	409	이 요청에 해당 채팅 세션을 사용할 수 없습니다.	같은 계정과 모델이 소유한 API 생성 세션을 사용하세요.
`chat_attachment_not_supported`	400	채팅 첨부 파일이 지원되지 않습니다.	Files API로 이미지를 업로드한 뒤 해당 `file_id`를 전달하세요.
`idempotency_conflict`	409	같은 멱등성 키를 다른 입력과 함께 다시 사용했습니다.	새 키를 사용하거나 완전히 같은 요청 본문을 다시 보내세요.
`insufficient_credits`	402	계정에 크레딧이 충분하지 않습니다.	크레딧을 추가하거나 비용이 더 낮은 요청을 선택하세요.
`internal_error`	500	요청을 완료할 수 없습니다.	멱등성 키를 유지해 재시도하거나 `requestId`와 함께 지원팀에 문의하세요.

요청 제한

Rivya는 API 키별로 애플리케이션 수준의 Public API 요청 제한을 적용합니다. 기본 운영 환경의 분당 한도는 PUBLIC_API_RATE_LIMIT_PER_MINUTE로 설정됩니다.

rate_limited 응답을 받으면 지수 백오프를 적용하세요. 짧은 간격으로 계속 재시도하지 마세요.

멱등성을 지키는 재시도

운영 환경의 모든 POST /api/v1/generations 및 POST /api/v1/chat/completions 요청에는 Idempotency-Key를 보내세요.

권장 패턴:

각 생성 요청마다 고유한 키를 만듭니다.
같은 요청 본문을 재시도할 때만 같은 키를 다시 사용합니다.
반환된 공개 작업 ID를 자체 작업 기록에 저장합니다.
Chat API에서 같은 대화를 이어가려면 반환된 session_id를 저장합니다.
모델, 프롬프트 또는 매개변수가 다른 요청에 같은 키를 재사용하지 않습니다.

요청을 제출한 뒤 네트워크 오류가 발생하면 같은 요청 본문과 Idempotency-Key로 재시도하세요. Rivya는 작업을 중복으로 만들지 않고 저장된 공개 응답을 반환할 수 있습니다.

재시도 여부 판단

다음 오류는 대기 시간을 점차 늘리며 재시도하세요.

public_api_disabled
rate_limited
internal_error
일시적인 네트워크 오류

다음 오류는 입력을 바꾸지 않은 채 재시도하지 마세요.

api_key_invalid
api_key_revoked
api_scope_denied
validation_failed
webhook_url_rejected
chat_model_not_supported
chat_session_conflict
chat_attachment_not_supported
idempotency_conflict
insufficient_credits

API 오류와 제한

오류 형태

안정적인 오류 코드

요청 제한

멱등성을 지키는 재시도

재시도 여부 판단

관련 페이지

목차