Sota Voice
Tài liệu

Mã lỗi

Định dạng lỗi chung và bảng mọi mã lỗi của API công khai.

Xem dạng Markdown

Mọi response lỗi dạng JSON có cùng một shape, giống OpenAI:

{
  "error": {
    "type": "insufficient_quota",
    "code": "insufficient_credit",
    "message": "Insufficient credit for this request.",
    "param": null
  }
}
  • code: mã ổn định, chữ thường. Rẽ nhánh theo field này.
  • type: nhóm lỗi (invalid_request_error, authentication_error, permission_error, insufficient_quota, rate_limit_error, api_error).
  • message: mô tả cho người đọc, có thể thay đổi; đừng parse.
  • param: field của request gây lỗi, nếu xác định được; ngược lại null.

Mỗi response có x-request-id (req_...); hãy gửi kèm khi liên hệ hỗ trợ.

Bảng mã lỗi

Bảng dưới đây sinh tự động từ đặc tả OpenAPI (/openapi.public.yaml), nên luôn khớp với API.

MãHTTPLoạiÝ nghĩa
invalid_request400invalid_request_errorYêu cầu không hợp lệ.
input_too_long400invalid_request_errorVăn bản quá dài.
unauthorized401authentication_errorKhóa API không hợp lệ hoặc thiếu.
insufficient_credit402insufficient_quotaSố dư ký tự không đủ. Hãy nạp thêm để tiếp tục.
account_suspended403permission_errorTài khoản đã bị tạm khóa. Vui lòng liên hệ hỗ trợ.
not_found404invalid_request_errorKhông tìm thấy nội dung yêu cầu.
model_not_found404invalid_request_errorKhông tìm thấy mô hình.
voice_not_found404invalid_request_errorKhông tìm thấy giọng nói.
job_not_found404invalid_request_errorKhông tìm thấy tác vụ.
job_not_cancellable409invalid_request_errorKhông thể hủy tác vụ này.
job_not_ready409invalid_request_errorTác vụ chưa hoàn thành.
voice_limit409invalid_request_errorBạn đã đạt số lượng giọng tùy chỉnh tối đa.
voice_name_taken409invalid_request_errorTên giọng này đã tồn tại.
voice_display_name_invalid400invalid_request_errorTên hiển thị phải dài 1 đến 60 ký tự.
voice_description_too_long400invalid_request_errorMô tả tối đa 500 ký tự.
idempotency_key_reused409invalid_request_errorKhóa idempotency đã được dùng cho yêu cầu khác.
job_expired410invalid_request_errorKết quả đã hết hạn.
request_too_large413invalid_request_errorYêu cầu quá lớn.
sample_too_large413invalid_request_errorTệp mẫu quá lớn.
invalid_webhook_url422invalid_request_errorURL webhook không hợp lệ.
idempotency_key_invalid422invalid_request_errorKhóa idempotency không hợp lệ.
consent_required422invalid_request_errorBạn cần xác nhận quyền sử dụng giọng nói này.
unsupported_audio422invalid_request_errorĐịnh dạng âm thanh không được hỗ trợ.
sample_too_long422invalid_request_errorMẫu âm thanh quá dài.
rate_limited429rate_limit_errorBạn thao tác quá nhanh. Vui lòng thử lại sau ít phút.
internal_error500api_errorĐã xảy ra lỗi hệ thống. Vui lòng thử lại sau.
upstream_unavailable503api_errorDịch vụ giọng nói tạm thời không khả dụng. Vui lòng thử lại.

Method không hỗ trợ trên một đường dẫn có tồn tại trả HTTP 405 với code: invalid_request.

Nên xử lý thế nào

MãCách xử lý
rate_limitedChờ Retry-After giây rồi thử lại. Xem Giới hạn tốc độ.
upstream_unavailable, internal_errorThử lại với backoff lũy thừa. Với upstream_unavailable của POST /v1/audio/speech, credit đã được hoàn.
insufficient_creditNạp thêm credit trong dashboard; không thử lại ngay.
unauthorizedKiểm tra khóa API (có thể đã bị thu hồi).
Nhóm invalid_request_errorSửa request; thử lại nguyên trạng sẽ lỗi tiếp.

Lỗi trong phiên WebSocket là sự kiện error với cùng các code; xem Voice agent qua WebSocket.