ErrorNotes

Sửa lỗi Mistral AI 422 Unprocessable Entity: MistralAPIStatusException do Tham Số API Sai

intermediate🧠 AI Tools2026-07-04| Python 3.8+, mistralai SDK 0.x / 1.x, Linux / macOS / Windows

Error Message

mistralai.exceptions.MistralAPIStatusException
#mistral-ai#python#api#422#llm#ai-tools#mistralai-sdk

TL;DR

Lỗi mistralai.exceptions.MistralAPIStatusException với HTTP 422 là lỗi validation tham số, không phải lỗi mạng hay xác thực. Mistral API đã parse JSON của bạn thành công — nhưng nội dung bên trong bị từ chối. Nguyên nhân phổ biến: sai tên model, temperature vượt quá 1.0, role message không hợp lệ, hoặc trường như frequency_penalty không được Mistral hỗ trợ. Tìm tham số lỗi trong trường detail và sửa lại.

Lỗi trông như thế nào

mistralai.exceptions.MistralAPIStatusException: Status: 422. Message: {"message": "Invalid request", "detail": [{"loc": ["body", "temperature"], "msg": "value is not a valid float", "type": "value_error.number.not_lt"}]}

SDK mistralai bọc mọi response HTTP không phải 2xx vào MistralAPIStatusException. HTTP 422 có nghĩa là Unprocessable Entity — server đã parse request thành công nhưng nội dung không qua được validation. Đây luôn là lỗi trong code của bạn. Không phải lỗi mạng, không phải sự cố hệ thống, không phải vấn đề xác thực. Response body cho bạn biết chính xác điều gì sai.

Nguyên nhân gốc rễ

  • Sai tên model hoặc model không được hỗ trợ — ví dụ "mistral-gpt-4" hoặc "mistral-large" (phải có hậu tố phiên bản, như -latest)
  • Temperature ngoài phạm vi cho phép — Mistral chấp nhận từ 0.0 đến 1.0; truyền 1.5 hoặc 2 sẽ gây lỗi 422
  • Role message không hợp lệ — chỉ có "user", "assistant", "system" và "tool" là hợp lệ
  • Sai kiểu dữ liệu cho tham số — ví dụ truyền max_tokens dưới dạng string "500" thay vì int 500
  • Trường không được hỗ trợ — các tham số đặc thù của OpenAI như frequency_penalty và presence_penalty không tồn tại trong API của Mistral
  • Danh sách messages rỗng hoặc sai định dạng — không có message nào, hoặc message thiếu key content

Bước 1 — Đọc trường detail

Trước khi đoán mò, hãy đọc lỗi. Mọi response 422 đều có mảng detail chỉ ra chính xác trường nào lỗi và lý do tại sao. Bắt exception và in ra:

import mistralai

try:
    response = client.chat.complete(model=model, messages=messages, temperature=temp)
except mistralai.exceptions.MistralAPIStatusException as e:
    print("Status:", e.http_status)
    print("Body:", e.message)   # contains the raw JSON detail
    raise

Trong output, loc trỏ đến trường lỗi — ví dụ ["body", "temperature"] — và msg cho biết rule nào bị vi phạm. Bắt đầu từ đây. Đừng đoán mò.

Bước 2 — Kiểm tra tên model

ID model phân biệt chữ hoa/thường và cần hậu tố phiên bản chính xác. "mistral-large" sẽ thất bại; "mistral-large-latest" mới đúng. Lấy danh sách hiện tại từ API để xem tài khoản của bạn có thể dùng những model nào:

from mistralai import Mistral

client = Mistral(api_key="your-api-key")
models = client.models.list()
for m in models.data:
    print(m.id)

Chọn một trong các ID được trả về — mistral-large-latest, mistral-small-latest, open-mistral-7b, v.v. Đừng tự đặt tên.

Bước 3 — Sửa phạm vi tham số

Mistral áp dụng kiểu dữ liệu và phạm vi giá trị nghiêm ngặt. Dưới đây là những gì mỗi tham số chấp nhận:

  • temperature: số float từ 0.0 đến 1.0 (bao gồm cả hai đầu)
  • top_p: số float từ 0.0 đến 1.0
  • max_tokens: số nguyên dương, không vượt quá context window của model
  • random_seed: số nguyên, không phải float
response = client.chat.complete(
    model="mistral-large-latest",
    messages=[
        {"role": "user", "content": "Hello"}
    ],
    temperature=0.7,      # float 0.0–1.0, NOT 1.5 or 2
    top_p=0.9,
    max_tokens=512,       # int, NOT "512"
    random_seed=42,       # int if set
)

Bước 4 — Kiểm tra mảng messages

Mỗi message cần có hai key: role và content. Role phải là một trong đúng bốn giá trị — bất kỳ giá trị nào khác đều gây lỗi 422.

# Sai — sẽ gây lỗi 422
messages = [
    {"role": "human", "content": "Hi"},   # role không hợp lệ
    {"role": "ai", "text": "Hello"},       # sai key + sai role
    {"role": "user"},                       # thiếu content
]

# Đúng
messages = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What is 2+2?"},
    {"role": "assistant", "content": "4"},
    {"role": "user", "content": "And 3+3?"},
]

Một điều nữa: messages=[] rỗng luôn thất bại. Bạn cần ít nhất một message.

Bước 5 — Xóa các tham số không được hỗ trợ

Đang migrate từ OpenAI? Một số tham số của OpenAI không tồn tại trong API của Mistral và sẽ gây lỗi 422 nếu bạn truyền vào:

# Các tham số tồn tại trong OpenAI nhưng KHÔNG có trong Mistral (sẽ gây lỗi 422)
# frequency_penalty, presence_penalty, logit_bias, logprobs, n

# Các tham số chat.complete() hợp lệ của Mistral (tính đến SDK v1.x)
response = client.chat.complete(
    model="mistral-small-latest",
    messages=messages,
    temperature=0.7,
    top_p=1.0,
    max_tokens=1024,
    stream=False,
    safe_prompt=False,
    random_seed=None,
)

Bước 6 — SDK không tương thích phiên bản

SDK mistralai có thay đổi API không tương thích ngược giữa phiên bản 0.x và 1.x. Cách gọi cũ là client.chat(); cách gọi mới là client.chat.complete(). Dùng sai pattern sẽ gây AttributeError. Truyền tham số kiểu cũ vào client mới sẽ gây lỗi 422.

# Kiểm tra phiên bản đang cài
pip show mistralai

# Nâng cấp lên phiên bản stable mới nhất
pip install --upgrade mistralai

Nếu bạn cần dùng phiên bản 0.x, hãy dùng pattern gọi của 0.x:

# mistralai 0.x
from mistralai.client import MistralClient
from mistralai.models.chat_completion import ChatMessage

client = MistralClient(api_key="your-api-key")
response = client.chat(
    model="mistral-small",
    messages=[ChatMessage(role="user", content="Hello")],
)

Kiểm tra lại

Chạy smoke test nhanh này sau khi đã sửa xong. Không có exception nghĩa là mọi thứ ổn:

from mistralai import Mistral

client = Mistral(api_key="your-api-key")
response = client.chat.complete(
    model="mistral-small-latest",
    messages=[{"role": "user", "content": "Say OK"}],
    temperature=0.5,
    max_tokens=10,
)
print(response.choices[0].message.content)  # Should print: OK

Tham khảo nhanh — hợp lệ và không hợp lệ

# KHÔNG HỢP LỆ → 422
client.chat.complete(
    model="mistral-large",          # thiếu -latest hoặc hậu tố phiên bản
    messages=[],                     # danh sách rỗng
    temperature=2.0,                 # ngoài phạm vi
    max_tokens="1000",               # string thay vì int
    frequency_penalty=0.5,           # tham số không được hỗ trợ
)

# HỢP LỆ
client.chat.complete(
    model="mistral-large-latest",
    messages=[{"role": "user", "content": "Hello"}],
    temperature=0.7,
    max_tokens=1000,
)

Đọc thêm

Related Error Notes

Khắc phục lỗi 'Invalid image URL' trong OpenAI Vision API (GPT-4o)

openai.BadRequestError: Error code: 400 - {'error': {'message': "Invalid image URL. Only 'data' URLs are supported for this request."}}

Khắc phục InstructorRetryException: Khi LLM không tuân thủ Schema của bạn

instructor.exceptions.InstructorRetryException: Failed to extract data after 3 retries

Cách sửa lỗi 'RuntimeError: This event loop is already running' với AsyncOpenAI trong Jupyter

RuntimeError: This event loop is already running. Passing coroutines is forbidden when an event loop is already running.