Mã lỗi
Định dạng lỗi chung và bảng mọi mã lỗi của API công khai.
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ạinull.
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ã | HTTP | Loại | Ý nghĩa |
|---|---|---|---|
invalid_request | 400 | invalid_request_error | Yêu cầu không hợp lệ. |
input_too_long | 400 | invalid_request_error | Văn bản quá dài. |
unauthorized | 401 | authentication_error | Khóa API không hợp lệ hoặc thiếu. |
insufficient_credit | 402 | insufficient_quota | Số dư ký tự không đủ. Hãy nạp thêm để tiếp tục. |
account_suspended | 403 | permission_error | Tài khoản đã bị tạm khóa. Vui lòng liên hệ hỗ trợ. |
not_found | 404 | invalid_request_error | Không tìm thấy nội dung yêu cầu. |
model_not_found | 404 | invalid_request_error | Không tìm thấy mô hình. |
voice_not_found | 404 | invalid_request_error | Không tìm thấy giọng nói. |
job_not_found | 404 | invalid_request_error | Không tìm thấy tác vụ. |
job_not_cancellable | 409 | invalid_request_error | Không thể hủy tác vụ này. |
job_not_ready | 409 | invalid_request_error | Tác vụ chưa hoàn thành. |
voice_limit | 409 | invalid_request_error | Bạn đã đạt số lượng giọng tùy chỉnh tối đa. |
voice_name_taken | 409 | invalid_request_error | Tên giọng này đã tồn tại. |
voice_display_name_invalid | 400 | invalid_request_error | Tên hiển thị phải dài 1 đến 60 ký tự. |
voice_description_too_long | 400 | invalid_request_error | Mô tả tối đa 500 ký tự. |
idempotency_key_reused | 409 | invalid_request_error | Khóa idempotency đã được dùng cho yêu cầu khác. |
job_expired | 410 | invalid_request_error | Kết quả đã hết hạn. |
request_too_large | 413 | invalid_request_error | Yêu cầu quá lớn. |
sample_too_large | 413 | invalid_request_error | Tệp mẫu quá lớn. |
invalid_webhook_url | 422 | invalid_request_error | URL webhook không hợp lệ. |
idempotency_key_invalid | 422 | invalid_request_error | Khóa idempotency không hợp lệ. |
consent_required | 422 | invalid_request_error | Bạn cần xác nhận quyền sử dụng giọng nói này. |
unsupported_audio | 422 | invalid_request_error | Định dạng âm thanh không được hỗ trợ. |
sample_too_long | 422 | invalid_request_error | Mẫu âm thanh quá dài. |
rate_limited | 429 | rate_limit_error | Bạn thao tác quá nhanh. Vui lòng thử lại sau ít phút. |
internal_error | 500 | api_error | Đã xảy ra lỗi hệ thống. Vui lòng thử lại sau. |
upstream_unavailable | 503 | api_error | Dị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_limited | Chờ Retry-After giây rồi thử lại. Xem Giới hạn tốc độ. |
upstream_unavailable, internal_error | Thử lại với backoff lũy thừa. Với upstream_unavailable của POST /v1/audio/speech, credit đã được hoàn. |
insufficient_credit | Nạp thêm credit trong dashboard; không thử lại ngay. |
unauthorized | Kiểm tra khóa API (có thể đã bị thu hồi). |
Nhóm invalid_request_error | Sử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.