Docs Rivya AI

Lỗi và giới hạn API

Xử lý mã lỗi công khai của Rivya API, giá trị HTTP status, rate limits, xung đột idempotency và quyết định retry.

Đánh giá lần cuối vào 2026/05/11

Rivya API trả về mã lỗi công khai ổn định trong JSON. Hãy coi giá trị error.code là hợp đồng tích hợp.

Cấu trúc lỗi

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

Giữ requestId trong log của bạn khi yêu cầu Rivya support điều tra một yêu cầu API thất bại.

Mã lỗi ổn định

CodeHTTP statusÝ nghĩaHành động đề xuất
public_api_disabled503Các lệnh gọi Public API đang tạm thời bị tắt.Retry sau hoặc dùng Studio thủ công.
api_key_missing401Yêu cầu không bao gồm Bearer API key.Gửi Authorization: Bearer rvya_sk_....
api_key_invalid401Key không thể được xác minh.Kiểm tra key và xoay vòng nếu cần.
api_key_revoked401Key đã bị thu hồi trong Settings.Tạo key mới.
api_key_expired401Key không còn hợp lệ.Tạo key mới.
api_scope_denied403Key không có scope bắt buộc.Tạo key có scope cần thiết.
rate_limited429Có quá nhiều yêu cầu trong cửa sổ hiện tại.Back off và retry sau.
validation_failed400Body, model, prompt hoặc params không hợp lệ.So sánh body của bạn với tham chiếu mô hình.
not_found404Tác vụ được yêu cầu không tồn tại hoặc không thuộc tài khoản.Kiểm tra public task ID và ranh giới tài khoản.
webhook_url_rejected400URL endpoint webhook không được phép.Dùng URL HTTPS công khai không có credentials, fragments, localhost hoặc địa chỉ mạng riêng.
chat_model_not_supported400Mô hình đã chọn không khả dụng cho Chat API.Đọc /api/v1/models và chọn mô hình chat khả dụng.
chat_session_conflict409Chat session không thể dùng cho yêu cầu này.Dùng session do API tạo thuộc cùng tài khoản và mô hình.
chat_attachment_not_supported400Chat attachment không được hỗ trợ.Tải ảnh lên qua Files API rồi truyền file_id của ảnh.
idempotency_conflict409Cùng một idempotency key được dùng lại với input khác.Dùng key mới hoặc gửi lại đúng cùng body.
insufficient_credits402Tài khoản không có đủ credits.Nạp credits hoặc chọn yêu cầu chi phí thấp hơn.
internal_error500Không thể hoàn tất yêu cầu.Retry với idempotency hoặc liên hệ support kèm requestId.

Rate limits

Rivya áp dụng rate limits Public API ở cấp ứng dụng theo từng API key. Giới hạn production mặc định được cấu hình bằng PUBLIC_API_RATE_LIMIT_PER_MINUTE.

Khi nhận rate_limited, hãy dùng exponential backoff. Đừng retry trong vòng lặp dày đặc.

Retry idempotent

Gửi Idempotency-Key với mọi yêu cầu production POST /api/v1/generations và POST /api/v1/chat/completions.

Mẫu khuyến nghị:

  • tạo một key duy nhất cho mỗi yêu cầu generation logic
  • chỉ dùng lại cùng key khi retry cùng body
  • lưu public task ID được trả về cùng bản ghi job của bạn
  • với Chat API, lưu session_id được trả về khi bạn muốn tiếp tục cùng cuộc trò chuyện
  • không dùng lại một key cho model, prompt hoặc params khác

Nếu mạng lỗi sau khi gửi, retry với cùng body và cùng Idempotency-Key. Rivya có thể trả về phản hồi công khai đã lưu thay vì tạo tác vụ trùng lặp.

Quyết định retry

Retry các lỗi này với backoff:

  • public_api_disabled
  • rate_limited
  • internal_error
  • lỗi mạng tạm thời

Đừng retry các lỗi này nếu chưa thay đổi input:

  • 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

Trang liên quan

Tín dụng API

Hiểu cách các lệnh gọi Rivya API dùng credits tài khoản, kiểm tra số dư, credits đã dự trữ, hoàn credits cho tác vụ thất bại và xử lý sự cố credits.

Files API

Tải lên tệp tham chiếu hình ảnh, video hoặc âm thanh cho yêu cầu generation của Rivya API, với kiểm tra MIME, giới hạn kích thước và duration tokens.

Mục lục

Cấu trúc lỗi
Mã lỗi ổn định
Rate limits
Retry idempotent
Quyết định retry
Trang liên quan