Rivya API 공개 오류 코드, HTTP status 값, rate limit, idempotency conflict, retry 결정을 처리하세요.

Rivya API는 안정적인 공개 오류 코드를 JSON으로 반환합니다. 통합 계약으로 error.code 값을 다루세요.

오류 형태

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

실패한 API 요청을 Rivya support가 조사해야 할 때는 로그에 requestId를 보관하세요.

안정적인 오류 코드

Code	HTTP status	Meaning	Suggested action
`public_api_disabled`	503	Public API 호출이 일시적으로 비활성화되었습니다.	나중에 다시 시도하거나 Studio를 수동으로 사용하세요.
`api_key_missing`	401	요청에 Bearer API key가 포함되지 않았습니다.	`Authorization: Bearer rvya_sk_...`를 보내세요.
`api_key_invalid`	401	key를 검증할 수 없습니다.	key를 확인하고 필요하면 교체하세요.
`api_key_revoked`	401	key가 Settings에서 폐기되었습니다.	새 key를 만드세요.
`api_key_expired`	401	key가 더 이상 유효하지 않습니다.	새 key를 만드세요.
`api_scope_denied`	403	key에 필요한 scope가 없습니다.	필요한 scope가 있는 key를 만드세요.
`rate_limited`	429	현재 window에서 요청이 너무 많습니다.	물러난 뒤 나중에 다시 시도하세요.
`validation_failed`	400	body, model, prompt, params가 유효하지 않습니다.	body를 model reference와 비교하세요.
`not_found`	404	요청한 task가 없거나 계정 소유가 아닙니다.	public task ID와 account boundary를 확인하세요.
`webhook_url_rejected`	400	webhook endpoint URL이 허용되지 않습니다.	credentials, fragments, localhost, private network addresses가 없는 HTTPS public URL을 사용하세요.
`chat_model_not_supported`	400	선택한 model은 Chat API에서 사용할 수 없습니다.	`/api/v1/models`를 읽고 사용 가능한 chat model을 선택하세요.
`chat_session_conflict`	409	chat session을 이 request에 사용할 수 없습니다.	같은 account와 model이 소유한 API 생성 session을 사용하세요.
`chat_attachment_not_supported`	400	chat attachment가 지원되지 않습니다.	Files API를 통해 image를 업로드하고 해당 `file_id`를 전달하세요.
`idempotency_conflict`	409	같은 idempotency key가 다른 input과 함께 재사용되었습니다.	새 key를 사용하거나 완전히 같은 body를 다시 보내세요.
`insufficient_credits`	402	account에 충분한 credits가 없습니다.	credits를 추가하거나 비용이 더 낮은 request를 선택하세요.
`internal_error`	500	request를 완료할 수 없습니다.	idempotency와 함께 retry하거나 `requestId`로 support에 문의하세요.

Rate Limits

Rivya는 API key별로 application-level Public API rate limits를 적용합니다. 기본 production limit은 PUBLIC_API_RATE_LIMIT_PER_MINUTE로 설정됩니다.

rate_limited를 받으면 exponential backoff를 사용하세요. 좁은 loop로 retry하지 마세요.

Idempotent Retries

모든 production POST /api/v1/generations 및 POST /api/v1/chat/completions request에는 Idempotency-Key를 보내세요.

권장 패턴:

논리적 generation request마다 고유한 key를 생성합니다.
같은 body를 retry할 때만 같은 key를 재사용합니다.
반환된 public task ID를 자체 job record에 저장합니다.
Chat API에서는 같은 conversation을 이어가려면 반환된 session_id를 저장합니다.
다른 model, prompt, params에는 하나의 key를 재사용하지 않습니다.

submission 이후 network가 실패하면 같은 body와 같은 Idempotency-Key로 retry하세요. Rivya는 duplicate task를 만들지 않고 저장된 public response를 반환할 수 있습니다.

Retry Decisions

다음은 backoff와 함께 retry하세요.

public_api_disabled
rate_limited
internal_error
temporary network failures

다음은 input을 바꾸지 않고 retry하지 마세요.

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 오류와 제한

오류 형태

안정적인 오류 코드

Rate Limits

Idempotent Retries

Retry Decisions

관련 페이지

목차