Mã lỗi

Khi lỗi, hãy kiểm tra mã trạng thái HTTP và trường message.

Nội dung lỗi

Lỗi nghiệp vụ luôn trả về code đọc được bằng máy để xử lý theo chương trình. Tham số không hợp lệ (validation) và route không tồn tại trả về định dạng Laravel chuẩn: { “message”: ”…”, “errors”: { … } }. Hãy kiểm tra dữ liệu trước khi gửi.

{
  "code": "insufficient_balance",
  "message": "Insufficient balance. Please top up and try again."
}

Lỗi

`code`	HTTP	Mô tả
`unauthorized`	401	Khóa API thiếu, không hợp lệ hoặc đã bị vô hiệu hóa.
`account_banned`	403	Tài khoản bị tạm ngưng. Vui lòng liên hệ hỗ trợ.
`invalid_realtime_request`	400	Yêu cầu realtime không hợp lệ (ví dụ: số điện thoại thiếu tiền tố quốc tế + khi bỏ trống country).
`idempotency_key_required`	400	Yêu cầu realtime bắt buộc có header Idempotency-Key.
`invalid_idempotency_key`	422	Idempotency-Key không hợp lệ: 1-128 ký tự gồm chữ, số và . _ : -
`idempotency_conflict`	409	Cùng một Idempotency-Key được dùng cho nội dung yêu cầu khác.
`request_in_progress`	409	Yêu cầu realtime giống hệt vẫn đang được xử lý. Thử lại sau ít phút (Retry-After: 1).
`empty_input`	422	Tệp tải lên không có dòng dữ liệu nào dùng được.
`product_not_found`	422	Slug sản phẩm gửi lên không tồn tại hoặc đã tắt.
`product_mode_not_supported`	422	Endpoint này không nhận chế độ sản phẩm này (sản phẩm realtime không dùng cho endpoint hàng loạt).
`invalid_country`	422	Sản phẩm không hỗ trợ quốc gia đã gửi.
`too_few_numbers`	422	Số lượng gửi dưới mức tối thiểu của sản phẩm.
`too_many_numbers`	422	Số lượng gửi vượt mức tối đa của nền tảng.
`insufficient_balance`	402	Số dư không đủ. Vui lòng nạp tiền rồi thử lại.
`realtime_disabled`	403	Tài khoản này chưa được bật kiểm tra realtime.
`realtime_rate_limited`	429	Vượt giới hạn tần suất realtime. Hãy tuân theo retry_after.
`product_pricing_unavailable`	503	Sản phẩm này chưa được cấu hình giá. Liên hệ hỗ trợ.
`detection_capacity_unavailable`	503	Hiện không còn dung lượng kiểm tra. Vui lòng thử lại sau.
`realtime_route_unavailable`	503	Không có tuyến realtime khả dụng. Vui lòng thử lại sau.
`realtime_fact_cache_unavailable`	503	Dịch vụ phụ trợ realtime tạm thời không khả dụng. Vui lòng thử lại sau.
`realtime_rate_limiter_unavailable`	503	Bộ giới hạn tần suất tạm thời không khả dụng. Vui lòng thử lại sau.
`internal_error`	500	Lỗi máy chủ ngoài dự kiến. Có thể thử lại an toàn với cùng Idempotency-Key.

Lỗi không có mã

Không phải mọi lỗi đều có code. Các endpoint tác vụ báo bốn tình huống chỉ bằng mã HTTP và message, vì những lỗi đó phát sinh trước khi đi vào luồng lỗi nghiệp vụ:

HTTP	Tình huống	Nội dung
`404`	`task_id` không tồn tại hoặc thuộc về tài khoản khác	chỉ `message`
`404`	`GET /v1/tasks/{token}/download` — tệp kết quả không khả dụng, đã hết hạn hoặc không còn tải được	chỉ `message`
`422`	`GET /v1/tasks/{token}/result` — kết quả chưa sẵn sàng: tác vụ chưa hoàn tất, tệp chưa được tạo hoặc đã hết hạn	chỉ `message`
`422`	Các tham số yêu cầu không vượt qua kiểm tra hợp lệ	`{ "message": …, "errors": { … } }`

Với những trường hợp này, hãy rẽ nhánh theo mã HTTP. message dành cho log và cho người đọc sự cố, không dùng cho luồng điều khiển.

Thử lại

Cách xử lý đúng khi gặp lỗi phụ thuộc vào việc lặp lại yêu cầu có thể cho ra kết quả khác hay không.

Cần xử lý trước

Thử lại nguyên trạng sẽ lặp lại đúng lỗi đó.

unauthorized, account_banned, invalid_realtime_request, idempotency_key_required, invalid_idempotency_key, idempotency_conflict, empty_input, product_not_found, product_mode_not_supported, invalid_country, too_few_numbers, too_many_numbers, insufficient_balance, realtime_disabled, product_pricing_unavailable

Đợi rồi thử lại

Tạm thời — cùng yêu cầu đó sẽ thành công về sau.

realtime_rate_limited, request_in_progress, detection_capacity_unavailable, realtime_route_unavailable, realtime_fact_cache_unavailable, realtime_rate_limiter_unavailable

Kết quả không chắc chắn

Yêu cầu có thể đã được áp dụng hoặc chưa. Hãy thử lại với cùng khóa.

internal_error