How to Test and Mock the Mistral AI API

The first integration test anyone writes against Mistral AI calls the real endpoint, asserts the model said something sensible, and passes. It keeps passing for about three weeks. Then it fails on a Sunday because of a rate limit, fails again on a fork's pull request because the key is not there, fails a third time because the model phrased its answer differently — and someone adds `retry: 3` and stops reading the output.

Why CI Should Not Call Mistral AI Directly

None of these are theoretical. Each one is a specific way a live-calling test suite degrades into a suite nobody trusts.

• Your build inherits their uptime. A Mistral AI incident becomes a red build across every branch, and the team learns that red means "probably upstream" — which is exactly the habit that lets a real regression through.
• Every pull request costs money. Token spend scales with contributor activity rather than with anything you would choose to pay for, and it is invisible until the invoice.
• Secrets have to exist everywhere CI runs. That includes fork pull requests, where a real MISTRAL_API_KEY either fails to exist (so external contributors can never get a green build) or does exist (which is a far worse problem).
• Model output is not deterministic. Asserting on generated prose produces failures that are not bugs, and the standard fix — loosening the assertion until it always passes — leaves a test that costs money and proves nothing.
• Rate limits look exactly like flakiness. A parallelised suite trips Mistral AI's limits precisely because it is fast, and the 429 arrives as an intermittent failure rather than as a clear message about concurrency.

The Four Layers, and What Each One Proves

Most teams have layer one and layer four missing, then wonder why a green suite did not prevent the outage. Each layer answers a different question, and no layer answers another layer's.

The line worth internalising: layers one and two are about your code, layer three is about your assumptions, and layer four is about Mistral AI. Adding more of the first two will never substitute for the last one.

A Mock You Can Paste In

Mistral AI is close to OpenAI-shaped, but served by its own SDK, and most codebases reach it through the `@mistralai/mistralai` client. Intercept at the HTTP boundary so the real client still runs — its validation, its error classes, its stream parsing all stay in the test.

import { setupServer } from 'msw/node';
import { http, HttpResponse } from 'msw';

const server = setupServer(
  http.post('https://api.mistral.ai/v1/chat/completions', () =>
    HttpResponse.json(SUCCESS_FIXTURE)),
);

beforeAll(() => server.listen({ onUnhandledRequest: 'error' }));
afterEach(() => server.resetHandlers());
afterAll(() => server.close());

// onUnhandledRequest: 'error' is the important line. Without it, a call your
// code makes to an endpoint you forgot to stub goes to the real api.mistral.ai
// with whatever key is in the environment.

Get the success fixture by making one real call and saving the response verbatim, not by writing out what you think the body looks like. A hand-authored fixture tests your code against your own assumptions, which it will always pass.

Simulate the Four Failures That Actually Happen

This is where mocking earns its cost. Every one of these paths runs for the first time during an incident unless a test made it run earlier.

// 1. Rate limited — assert the backoff reads retry-after.
http.post('https://api.mistral.ai/v1/chat/completions', () =>
  new HttpResponse(null, { status: 429, headers: { 'retry-after': '2' } }));

// 2. Server error — assert a bounded retry, then a clean surfaced failure.
http.post('https://api.mistral.ai/v1/chat/completions', () =>
  new HttpResponse(null, { status: 500 }));

// 3. Timeout — assert your own deadline fires before the user's patience does.
http.post('https://api.mistral.ai/v1/chat/completions', async () => {
  await new Promise((r) => setTimeout(r, 30_000));
  return HttpResponse.json(SUCCESS_FIXTURE);
});

// 4. Truncated stream — the one nobody tests, and the one that
//    quietly writes half an answer into your database as if it were whole.
http.post('https://api.mistral.ai/v1/chat/completions', () => {
  const stream = new ReadableStream({
    start(controller) {
      controller.enqueue(new TextEncoder().encode(
        'data: {"choices":[{"delta":{"content":"The ans"}}]}\n\n'));
      controller.close(); // no [DONE], no finish_reason
    },
  });
  return new HttpResponse(stream, {
    headers: { 'Content-Type': 'text/event-stream' },
  });
});

The Mistral Trap: Mocking the SDK Instead of the Wire

Mistral ships its own client rather than asking you to repoint the OpenAI SDK, and the path of least resistance in a test file is to `jest.mock('@mistralai/mistralai')` and hand back an object shaped like whatever your code happens to read. That mock passes forever. It also stops testing anything the moment Mistral changes a field name, adds a required parameter, or alters how the client raises an error — because the thing you replaced is the thing that would have changed.

Mock at the HTTP boundary instead. Intercept the request to api.mistral.ai and return a real response body, so your code still runs through the actual client: its validation, its error classes, its streaming parser. When the SDK's behaviour changes under you, a wire-level mock notices at upgrade time; an SDK-level mock notices in production.

The `-latest` model aliases are the same category of hazard in a different coat. Pinning `mistral-large-latest` in a fixture records the behaviour of whichever snapshot was live the day you recorded it, and the alias silently moves. If a test asserts anything about the *content* of a completion, pin a dated model id in the test path so the assertion has something stable to be true about.

Intercept the wire, keep the real client

import { setupServer } from 'msw/node';
import { http, HttpResponse } from 'msw';

// The real Mistral client still runs — only the network is faked.
export const server = setupServer(
  http.post('https://api.mistral.ai/v1/chat/completions', async ({ request }) => {
    const body = await request.json();

    // Assert on what your code actually sent.
    if (!body.model || !Array.isArray(body.messages)) {
      return HttpResponse.json({ message: 'invalid request' }, { status: 422 });
    }

    return HttpResponse.json({
      id: 'cmpl-test',
      object: 'chat.completion',
      model: body.model,
      choices: [{
        index: 0,
        message: { role: 'assistant', content: 'ok' },
        finish_reason: 'stop',
      }],
      usage: { prompt_tokens: 9, completion_tokens: 1, total_tokens: 10 },
    });
  }),
);

The One Test That Should Hit the Real API

Keep exactly one, keep it out of the pull-request path, and give it a narrow job: prove that the credentials work, that the model id still resolves, and that the response still has the shape your fixtures claim. It is the only thing standing between a fully mocked suite and a fixture that has quietly stopped describing reality.

// One test. Runs pre-deploy or nightly, never on a pull request.
// Its job is to prove the assumptions the mocks are built on.
const res = await fetch('https://api.mistral.ai/v1/chat/completions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MISTRAL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'mistral-large-latest',
    messages: [{ role: 'user', content: 'Reply with the single word: ok' }],
    max_tokens: 5,
  }),
});

if (!res.ok) {
  throw new Error(`Mistral AI smoke test failed: ${res.status}`);
}

// Assert the SHAPE the fixtures encode, not the words that came back.
const body = await res.json();
assertMatchesFixtureShape(body);

Run it on a schedule and before deploy. Do not run it on pull requests, because that reintroduces every problem in the first section — the secret exposure, the fork failures, the upstream-outage red builds — in exchange for a signal you already get nightly.

Where Testing Stops and Monitoring Starts

A test suite runs when you push. An outage happens when it happens. That gap is the entire reason a green pipeline and a broken product coexist so comfortably: nothing in CI is watching Mistral AI at 02:00 on a Saturday, and a nightly smoke test tells you about a failure up to twenty-four hours after your users found it.

The layer that closes the gap is independent probing — real requests to api.mistral.ai on an interval, from outside your infrastructure, alerting on both errors and latency. It is also what answers the question your team will actually ask during an incident, which is never "did the tests pass" but always "is it us or is it them?"

Frequently Asked Questions

Related Guides

• Mistral AI API Error Codes Explained
• Mistral AI API Rate Limits Explained
• Mistral AI API Key Setup Guide
• Mistral AI API Streaming Errors
• Mistral AI API Failover Guide
• Mistral AI API Monitoring Guide
• Is Mistral AI Down? Outage Checking Guide
• Live Mistral AI Status Check