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, internal_error hoặc service_unavailable. 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 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.

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 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.