Xử lý lỗi

Cần phân biệt hai trường hợp: API từ chối ngay request, hoặc đã nhận request nhưng job gặp lỗi trong lúc xử lý. Trường hợp sau có status là failed.

Đọc response lỗi

Với các endpoint /v1, lỗi request luôn có cấu trúc sau:

{
  "error": {
    "code": "insufficient_minutes",
    "message": "Not enough minutes",
    "retryable": false,
    "action_url": "https://transcript1.com/dashboard/billing",
    "minutes_needed": 20,
    "minutes_remaining": 3
  }
}

Dựa vào code để viết logic xử lý, không dựa vào câu chữ trong message. Bạn có thể hiển thị message cho người dùng, nhưng nội dung này có thể thay đổi. Giá trị retryable: true cho biết request có thể thành công nếu thử lại sau.

Tùy mã lỗi, object còn có các trường sau bên cạnh retryable:

Request bị từ chối

Nếu trình duyệt xác thực bằng cookie đăng nhập thay cho bearer token, API còn kiểm tra origin. Request từ website khác sẽ nhận 403 forbidden_origin. Cơ chế này không áp dụng cho lệnh gọi API có header Authorization.

Response 429 luôn có header Retry-After, tính bằng giây. Xem các hạn mức cụ thể trong Thanh toán và giới hạn.

Khi nào nên gửi lại request?

• Chỉ tự thử lại nếu retryable là true: rate_limited, too_many_active_jobs, too_many_live_sessions, live_capacity, internal_error, service_unavailable, hoặc topup_needs_user có reason là pending hay in_progress. Có Retry-After thì chờ đúng thời gian đó; không có thì tăng dần thời gian chờ giữa các lần.
• Gửi lại POST /v1/transcriptions hoặc POST /v1/topups với nguyên Idempotency-Key đã dùng. Nếu request đầu đã thành công, cách này tránh tạo thêm lần tính phí.
• Gặp mã khác thì sửa request trước, không gửi lại nguyên trạng.

Chuyển thành văn bản trực tiếp

POST /v1/live/sessions và các endpoint trực tiếp khác dùng cùng cấu trúc lỗi. invalid_request, unsupported_language, insufficient_minutes và email_not_verified cũng áp dụng cho chúng, cùng với các mã trực tiếp trong bảng ở trên. Việc tạo phiên không idempotent, nên thử lại sau too_many_live_sessions hoặc live_capacity sẽ tạo một phiên mới.

Sau khi phiên đã tồn tại, sự cố đến qua WebSocket dưới dạng sự kiện error và mã đóng, không phải lỗi HTTP. Xem Chuyển thành văn bản trực tiếp để biết mọi sự kiện.

Phiên trực tiếp kết thúc vì lý do như balance_exhausted hay idle_timeout không phải là lỗi: nó gửi session.ended kèm lý do kết thúc và được lưu. Xem Lý do kết thúc.

Job lỗi trong lúc xử lý

Job có thể gặp lỗi sau khi API đã trả response. Khi status là failed, object transcription chứa error: { "code", "message" }. Kiểm tra error mỗi khi poll trạng thái hoặc nhận webhook transcription.failed. Nếu bản dịch thất bại, webhook transcription.translation.failed được gửi đi và bản chép lời không bao giờ bị lỗi vì việc đó.

Nếu job thất bại hoặc bạn hủy, bạn không mất phí. Phút đã trừ cho job đó sẽ được hoàn lại.