Most Mistral API errors are not model capability problems. They come from credentials, paths, parameters, rate limits, or networking. The right troubleshooting order is: read the HTTP status code and error type first, then check the request ID and a minimal reproduction, and only then adjust prompts or change models. Done in the opposite order, a configuration error can easily be misdiagnosed as a weak model.

This article works through 401, 403, 404, 422, 429, 5xx, and timeouts one by one, with retry code, concurrency governance, log fields, and a support ticket checklist. Specific quotas, error messages, and interface behavior are governed by the Mistral official documentation and console.

Note: Mistral is a trademark of its owner. This article is for technical discussion only. Error codes, rate-limit rules, and interface behavior may change between versions; the official documentation and console take precedence.

1. Read the status code first, not the prompt

Status or symptom Common meaning Typical cause Order of handling
401 Authentication failed Missing key, malformed key, revoked key Fix credentials first
403 Not permitted Model not enabled, insufficient workspace role, regional restriction Check account and permissions
404 Path or model not found Wrong base URL, duplicated path, retired model name Check the address and model name
422 Request semantics invalid Missing field, wrong type, unsupported parameter Read the error detail and fix parameters
429 Rate limit or quota triggered Sudden concurrency spike, shared key, retry storm Back off, reduce concurrency
5xx Upstream service failure Service overload, gateway error, transient fault Limited retries, switch channel
Timeout Connection or read timeout Network jitter, long output, proxy idle timeout Isolate layer by layer

At minimum, log the timestamp, status code, error type, model name, elapsed time, and request ID. Do not log full keys or raw user content.

2. 401 and 403: authentication and authorization

A 401 means the identity was not verified and is usually unrelated to model capability or balance. Check in this order:

  • Is the header Authorization: Bearer <key>, rather than a custom field or an older authentication style?
  • Are there spaces, line breaks, or extra quotation marks around the key? Copying from a chat window is the most common source.
  • Are the environment variables actually loaded? Printing only the prefix is enough to confirm; never print the full key.
  • Has the key been deleted, rotated, or disabled? Is the test environment accidentally using a production key?
  • Do the base URL and the key belong to the same platform? Sending a key from platform A to platform B returns 401 immediately.
  • Is a reverse proxy or SDK overwriting or dropping the Authorization header?

A 403 means "the identity is recognized but not permitted." Common causes include a current account or workspace lacking permission to call that model, insufficient role permissions, a model not opened to the current region, or a request sent to an endpoint that is not enabled. Check the model list and member permissions in the console first, then call a model known to be available with the same key as a control.

3. 404 and 422: addresses, model names, and parameters

A 404 usually means the request hit a path or model that does not exist, not that the API is down. Common causes include a wrong base URL, an extra or missing /v1, an SDK that automatically appends a path while handwritten code appends it again, a retired model version in the model name, and a gateway without the corresponding route configured. Send a minimal request to the full address first, read the error in the response body, and then compare it item by item with the console's model list.

A 422 means the request is well-formed but semantically invalid. It commonly appears when a required field is missing, a field type is wrong, messages is empty, max_tokens exceeds the allowed range, a parameter is unsupported by the current model, or the JSON structure is corrupted. The response body usually indicates the field location and reason. Read the detail or error field and fix according to the message; do not retry blindly.

4. 429: rate limits, concurrency, and retry storms

A 429 means the request exceeded a rate, concurrency, or quota limit. It does not mean the balance is insufficient. Common triggers:

  • Multiple services share one key and compete for the same quota.
  • Batch jobs start at the top of the hour and create a traffic pulse.
  • Retries have no backoff, so failures generate more failures and form a retry storm.
  • Long outputs or streaming requests hold connections open, leaving less room for concurrency.
  • Test, staging, and production environments are not separated, so test traffic exhausts the production quota.

When handling a 429, first check whether the response includes a rate-limit hint such as Retry-After; if so, wait as instructed. Otherwise use exponential backoff with random jitter. At the same time, reduce concurrency, add a queue and token bucket for batch jobs, and set separate limits by model, key, and environment. Do not treat retries as capacity expansion; retries absorb short spikes but do not solve a persistent capacity shortage.

5. 5xx and timeouts: upstream, network, and streaming

5xx covers 500, 502, 503, and 504, and may come from upstream overload, a gateway forwarding failure, or a transient fault. First confirm the scope: is every model failing, or only one model, one region, or one route? Short 5xx bursts can be retried a limited number of times; persistent 5xx should trigger lower concurrency, a switch to a backup channel, and a support ticket with the request IDs.

Timeouts should be separated into connection timeouts, read timeouts, and streaming idle timeouts. Connection timeouts are usually related to networking, DNS, or a proxy. Read timeouts often involve long outputs, complex reasoning, and upstream queuing. Streaming requests may also be cut off by a proxy's idle timeout. Set explicit connection and read timeouts on the client, and configure idle timeouts and reconnection policy for streaming. For requests with side effects, do not resend immediately after a timeout; confirm whether the upstream already executed the operation.

6. Request IDs and logs: the basis for troubleshooting

The request ID is the anchor for cross-team troubleshooting. Responses and error bodies usually include a request identifier, commonly in the x-request-id header. Whether you call directly or through a gateway, record it and associate it with the business reference number in your logs.

Recommended log fields include: timestamp, request ID, status code, error type, model name, input and output token counts, elapsed time, retry count, whether the request was streamed, and the upstream channel. Redact user content or keep only a summary, and log only the key prefix. A screenshot of an error without a request ID makes it very hard for a support team to locate the specific request.

7. Retries and backoff: what can be retried, and how

A retry must satisfy three conditions: the error is recoverable, the request is repeatable, and retries have a limit. Do not retry 401, 403, 404, or 422; these are configuration or parameter problems, and retrying only wastes time. 429, 5xx, and timeouts can be retried a bounded number of times, and Retry-After should be honored first.

The example below combines retryable statuses, exponential backoff, random jitter, and request ID logging. Production should also add circuit breaking, metric reporting, and idempotency checks before resending.

import os
import random
import time

import requests

API_KEY = os.environ["MISTRAL_API_KEY"]
URL = "https://api.mistral.ai/v1/chat/completions"
RETRY_STATUS = {429, 500, 502, 503, 504}


def wait_seconds(resp, attempt):
    value = resp.headers.get("Retry-After") if resp is not None else None
    if value:
        try:
            return min(float(value), 60.0)
        except ValueError:
            pass
    return min(2 ** attempt + random.random(), 30.0)


def chat(payload, max_retries=4):
    last_error = None
    for attempt in range(max_retries + 1):
        try:
            resp = requests.post(
                URL,
                headers={
                    "Authorization": f"Bearer {API_KEY}",
                    "Content-Type": "application/json",
                },
                json=payload,
                timeout=(5, 60),  # 5 seconds connect, 60 seconds read
            )
        except requests.Timeout as exc:
            last_error = exc
            if attempt == max_retries:
                break
            time.sleep(wait_seconds(None, attempt))
            continue

        request_id = resp.headers.get("x-request-id", "unknown")
        if resp.status_code == 200:
            return resp.json()

        if resp.status_code in RETRY_STATUS:
            last_error = RuntimeError(
                f"HTTP {resp.status_code}, request_id={request_id}"
            )
            if attempt == max_retries:
                break
            time.sleep(wait_seconds(resp, attempt))
            continue

        # Retrying 401/403/404/422 is pointless; surface the config or parameter problem.
        raise RuntimeError(
            f"HTTP {resp.status_code}, request_id={request_id}, "
            f"body={resp.text[:500]}"
        )

    raise RuntimeError(f"retry exhausted: {last_error}")

Beyond retries, govern concurrency: set a semaphore per model, a queue for batch jobs, different keys for different environments, and an alert on the 429 share. Treat rate limiting as a capacity problem, not an occasional error.

8. Support ticket checklist

Before contacting platform support, organize the information below; it can significantly shorten the investigation:

  1. The time and time range, with the time zone, and whether the failure is continuous or intermittent.
  2. The full request ID, along with the status code and error response body, properly redacted.
  3. The request URL, model name, whether streaming was used, and whether tool calling or structured output was involved.
  4. A minimal reproducible request, with business-irrelevant fields removed and necessary parameters kept.
  5. The scope of impact: how many users, which regions, which network environments, and whether all models failed.
  6. Recent changes: whether keys were rotated, models upgraded, or proxy or gateway configuration adjusted.
  7. Troubleshooting already performed and its results, including comparisons after changing the key, model, network, or concurrency.

Frequently asked questions

I changed the key and still get 401. What now?

First confirm that the new key belongs to the platform behind the current base URL, then check whether the environment variables are actually loaded and whether the proxy passes the Authorization header through. Sending a minimal request to both the official endpoint and the gateway endpoint quickly separates a key problem from a route problem.

Does a 429 mean the account balance is low?

No. A 429 means the request exceeded a rate, concurrency, or quota limit; insufficient balance usually returns a different error or explains itself in the response body. Check concurrency, shared keys, and the retry policy first, then check account status.

What is the difference between 422 and 400?

Both can indicate parameter problems, but 422 emphasizes a well-formed request with invalid semantics, such as a wrong field type or a missing required item. In practice, rely on the field hints in the response body rather than guessing from the status code alone.

Can I resend a request immediately after a timeout?

It depends on whether the request has side effects. Pure queries can be retried a limited number of times; operations such as placing an order, charging a card, or sending a message require confirming whether the upstream already executed, or using an idempotency key for deduplication. A timeout only means the client did not receive a result; it does not mean the upstream did not process the request.

What should I prepare before opening a ticket?

Prepare the time range, request ID, status code, error response body, model name, minimal reproduction, and scope of impact. Then describe recent changes and the troubleshooting already performed, so the support team can locate the specific path quickly.

Next step

Create a test key in the ZSQH AI Gateway, rehearse 401, 422, 429, and a timeout once each, and then connect production monitoring. Model availability and billing rules are listed on the model pricing page.

Related reading: