Anthropic API 404 not_found_error: "model: …" — vì sao tên mô hình tồn tại vẫn trả về 404

Điểm gây nhầm lẫn của lỗi 404 này là mô hình thường thực sự tồn tại — trong tài liệu Anthropic, một bài blog hoặc mã nguồn từ quý trước. Nhưng nó không tồn tại trong danh sách mà khóa API của bạn được phép gọi hôm nay.

Lỗi

phản hồi (HTTP 404)

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "model: claude-3-5-sonnet"
  }
}

Tổng quan nguyên nhân và cách khắc phục

Nguyên nhân	Cách khắc phục
Snapshot có ngày đã ngừng sử dụng	Snapshot bị phản đối theo lịch công bố rồi ngừng phân giải. Hãy chuyển sang snapshot hiện tại.
Một alias chưa từng tồn tại	`claude-3-5-sonnet` là một họ mô hình, không phải id có thể gọi. Id Anthropic chứa phiên bản hoặc hậu tố ngày.
Mô hình có thật nhưng chưa được bật cho tài khoản của bạn	Các mô hình mới nhất có thể bị giới hạn theo cấp. Lỗi 404 không thể phân biệt với lỗi gõ sai — hãy kiểm tra endpoint models, không phải tài liệu.
Tên mô hình OpenAI trên endpoint Anthropic	`gpt-4o` tại api.anthropic.com là mô hình không tồn tại, không phải lỗi định tuyến. Nếu muốn dùng một endpoint cho cả hai, hãy sử dụng gateway.

Hỏi API, không hỏi tài liệu

Tài liệu mô tả danh mục; endpoint models mô tả danh mục của bạn. Khi hai bên không khớp, endpoint là nguồn đúng. Bất kỳ mục nào vắng trong danh sách này sẽ trả về 404 dù có vẻ mới ở nơi khác.

list-models.sh

curl -s https://api.anthropic.com/v1/models \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  | grep '"id"'

Ghim có chủ đích, nâng cấp có chủ đích

Mã hóa cứng một snapshot theo ngày giúp tái lập kết quả nhưng cũng có thể tạo ra 404 trong tương lai vào một ngày bạn không chọn. Đọc model id từ cấu hình biến việc sửa lỗi thành giá trị lúc triển khai thay vì thay đổi mã — và chính cơ chế này cho phép chuyển dự phòng khi mô hình bận chứ không phải không tồn tại.

model_config.py

import os

# One place to change when a snapshot retires.
MODEL = os.environ.get("LLM_MODEL", "claude-sonnet-5")

resp = client.chat.completions.create(
    model=MODEL,
    messages=[{"role": "user", "content": "ping"}],
)

Phân biệt 404 với 400 và 403

404 nghĩa là tên không phân giải được thành gì. 400 nghĩa là tên đúng nhưng yêu cầu không đúng (tham số sai, nội dung không hợp lệ). 403 nghĩa là mô hình tồn tại nhưng bạn không được phép sử dụng. Chỉ lỗi 404 được khắc phục bằng cách đổi chuỗi mô hình.

Nếu bạn gọi qua Kunavo

Danh mục của Kunavo là danh sách do endpoint /v1/models trả về, và mọi id trong đó đều có thể gọi bằng bất kỳ khóa nào đã nạp tiền — không có giới hạn mô hình theo tài khoản, nên nguyên nhân “có thật nhưng chưa được bật cho bạn” ở trên không xảy ra. Vì cùng một endpoint phục vụ tên Claude và GPT, id OpenAI cũng không phải lỗi dùng sai endpoint; nó chỉ được định tuyến. Việc ngừng sử dụng mô hình vẫn xảy ra ở thượng nguồn, và khi một mô hình bị rút, id của nó sẽ được chuyển hướng hoặc ghi rõ trong tài liệu thay vì âm thầm trả về 404. Id hiện tại và đơn giá theo token có tại bảng giá Claude API.

Câu hỏi thường gặp

404 có bao giờ là lỗi tạm thời không?

Không. Không giống 429, 500 và 529, thử lại 404 với cùng chuỗi mô hình chỉ có thể thất bại lần nữa. Hãy đổi chuỗi hoặc dừng lại.

Làm sao biết khi nào một snapshot ngừng hoạt động?

Anthropic công bố ngày ngừng sử dụng cho các snapshot theo ngày. Nếu bạn ghim snapshot, lịch đó là một mục trong lịch; nếu đọc id từ cấu hình, đây là thay đổi một dòng.

Vì sao khóa của đồng nghiệp tôi hoạt động với cùng tên?

Tính khả dụng của mô hình có thể khác nhau theo cấp tài khoản. So sánh hai phản hồi /v1/models — sự khác biệt đó chính là câu trả lời.

Hướng dẫn liên quan

Thông tin chi tiết hơn về ý nghĩa lỗi có trong tài liệu tham chiếu lỗi; bạn chỉ mất một phút để lấy khóa qua đăng ký và hướng dẫn xác thực.