Lỗi và thử lại

Chẩn đoán bằng mã lỗi và request ID.

HTTP 429 có thể do tiếp nhận cục bộ, hàng đợi đầy hoặc nhà cung cấp giới hạn. Đọc nội dung lỗi và Retry-After; không diễn giải là RPM/TPM không giới hạn.

Tôn trọng Retry-After; dùng exponential backoff có jitter, giới hạn số lần và tổng thời gian thử lại. Với tác vụ video đã có thể được tạo, tra cứu ID trước để tránh yêu cầu trùng.

Lưu x-cadhayvn-request-id nếu có và thời điểm lỗi để đối chiếu. Không gửi khóa API hoặc dữ liệu nhạy cảm trong báo lỗi.

Mã lỗi

HTTP	Loại lỗi	Nguyên nhân
400	invalid_request_error	JSON sai hoặc thiếu tham số
401	authentication_error	Thiếu key, key sai hoặc đã thu hồi
402	insufficient_balance	Hết số dư ví — cần nạp thêm
413	request_too_large	Nội dung yêu cầu vượt 20 MB
429	rate_limit_error	HTTP 429 có thể do tiếp nhận cục bộ, hàng đợi đầy hoặc nhà cung cấp giới hạn. Đọc nội dung lỗi và Retry-After; không diễn giải là RPM/TPM không giới hạn.
502	api_error	Không kết nối được model từ nhà cung cấp thượng nguồn
503	service_unavailable	Tạm thời chưa sẵn sàng hoặc đang bảo trì; kiểm tra request ID và thời điểm trước khi thử lại.

{
  "type": "error",
  "error": {
    "type": "insufficient_balance",
    "message": "Số dư đã hết. Nạp thêm tại https://api.cadhayvn.com/dashboard/topup"
  }
}

Khắc phục sự cố

Xem trạng thái model trong Bảng giá

Lưu x-cadhayvn-request-id nếu có và thời điểm lỗi để đối chiếu. Không gửi khóa API hoặc dữ liệu nhạy cảm trong báo lỗi.

Triệu chứng	Nguyên nhân thường gặp	Cách xử lý
404 hoặc “Not Found”	Dán sai URL gốc — thừa hoặc thiếu đuôi /v1.	Công cụ kiểu Anthropic dùng https://api.cadhayvn.com; công cụ kiểu OpenAI dùng https://api.cadhayvn.com/v1.
401 authentication_error	Key sai, đã thu hồi, hoặc app vẫn dùng key cũ đã lưu.	Tạo key mới trong bảng điều khiển, xoá key cũ trong app rồi khởi động lại app.
402 insufficient_balance	Hết số dư ví.	Nạp thêm tại trang Nạp tiền.
429 rate_limit_error	HTTP 429 có thể do tiếp nhận cục bộ, hàng đợi đầy hoặc nhà cung cấp giới hạn. Đọc nội dung lỗi và Retry-After; không diễn giải là RPM/TPM không giới hạn.	Tôn trọng Retry-After; dùng exponential backoff có jitter, giới hạn số lần và tổng thời gian thử lại. Với tác vụ video đã có thể được tạo, tra cứu ID trước để tránh yêu cầu trùng.
Claude Code cứ đòi đăng nhập	Máy còn phiên đăng nhập tài khoản Anthropic cũ.	Chạy /logout trong Claude Code, đặt ANTHROPIC_AUTH_TOKEN rồi mở lại terminal.
App báo model không tồn tại	Tên model gõ sai hoặc app tự thêm tiền tố nhà cung cấp.	Gọi GET /v1/models để lấy đúng tên, và bỏ các tiền tố kiểu anthropic/ nếu app không yêu cầu.
Gửi ảnh thì lỗi	App gửi ảnh theo định dạng model đó không nhận, hoặc ảnh quá lớn.	Chỉ dùng model có nhãn Vision, nén ảnh và giữ toàn bộ yêu cầu dưới 20 MB.
Biến môi trường không có tác dụng	Terminal cũ vẫn giữ giá trị cũ, hoặc app đọc cấu hình trong tệp riêng.	Mở terminal mới (Windows: đăng xuất/đăng nhập lại), và kiểm tra xem app có tệp cấu hình ghi đè biến môi trường không.

Ví dụ được rà soát ở mức mã và kiểm thử cục bộ; không khẳng định đã chạy trên mọi phiên bản ứng dụng. Hãy kiểm tra cấu hình, gửi một yêu cầu nhỏ và xác nhận usage trước khi dùng thật.