mistral-common-errors

Mistral AI Common Errors

Overview

Quick reference for diagnosing and fixing Mistral AI API errors. Covers HTTP status codes, SDK-specific issues, streaming failures, and tool calling problems with real solutions.

Prerequisites

• Mistral AI SDK installed
• MISTRAL_API_KEY configured
• Access to application logs

Instructions

Step 1: Quick Diagnostic

set -euo pipefail
# Test API connectivity and auth
curl -s -w "\nHTTP Status: %{http_code}\n" \
  -H "Authorization: Bearer ${MISTRAL_API_KEY}" \
  https://api.mistral.ai/v1/models | jq '.data[].id' 2>/dev/null || echo "FAILED"

# Check env
echo "Key set: ${MISTRAL_API_KEY:+yes}"
echo "Key length: ${#MISTRAL_API_KEY}"

Step 2: Error Reference

---

401 Unauthorized

Error: Authentication failed. Invalid API key.

Causes: Key missing, expired, revoked, or wrong workspace.

Fix:

const apiKey = process.env.MISTRAL_API_KEY;
if (!apiKey) throw new Error('MISTRAL_API_KEY is not set');

// Test the key
const client = new Mistral({ apiKey });
try {
  await client.models.list();
} catch (e: any) {
  if (e.status === 401) {
    console.error('API key invalid — regenerate at console.mistral.ai');
  }
}

Verify manually:

set -euo pipefail
curl -H "Authorization: Bearer ${MISTRAL_API_KEY}" https://api.mistral.ai/v1/models

---

429 Too Many Requests

Error: Rate limit exceeded. Retry-After: 60

Causes: Exceeded RPM (requests/min) or TPM (tokens/min) for your tier.

Fix:

async function withBackoff<T>(fn: () => Promise<T>, maxRetries = 5): Promise<T> {
  for (let i = 0; i <= maxRetries; i++) {
    try {
      return await fn();
    } catch (error: any) {
      if (error.status !== 429 || i === maxRetries) throw error;
      const wait = Math.min(2 ** i * 1000, 60_000);
      console.warn(`Rate limited, retrying in ${wait}ms...`);
      await new Promise(r => setTimeout(r, wait));
    }
  }
  throw new Error('Max retries exceeded');
}

Check your limits: Visit console.mistral.ai/limits for workspace RPM/TPM caps.

---

400 Bad Request — Invalid Model

{"message": "Unknown model: mistral-ultra"}

Fix: Use valid model IDs:

const VALID_MODELS = [
  'mistral-large-latest',
  'mistral-small-latest',
  'codestral-latest',
  'pixtral-large-latest',
  'mistral-embed',
  'mistral-moderation-latest',
] as const;

List available models dynamically:

set -euo pipefail
curl -H "Authorization: Bearer ${MISTRAL_API_KEY}" \
  https://api.mistral.ai/v1/models | jq -r '.data[].id' | sort

---

400 Bad Request — Invalid Messages

{"message": "messages must be a non-empty array"}

Fix: Validate message structure before sending:

function validateMessages(messages: any[]): void {
  if (!messages?.length) throw new Error('Messages array empty');
  const validRoles = ['system', 'user', 'assistant', 'tool'];
  for (const msg of messages) {
    if (!validRoles.includes(msg.role)) {
      throw new Error(`Invalid role: "${msg.role}"`);
    }
    if (!msg.content && !msg.toolCalls) {
      throw new Error(`Message with role "${msg.role}" has no content`);
    }
  }
}

---

400 Bad Request — Tool Call Errors

{"message": "tool_call_id is required for tool messages"}

Fix: Every tool result must include the matching toolCallId:

// After receiving tool_calls from the model
for (const call of response.choices[0].message.toolCalls) {
  const result = await executeFunction(call.function.name, call.function.arguments);
  messages.push({
    role: 'tool',
    name: call.function.name,
    content: JSON.stringify(result),
    toolCallId: call.id,  // REQUIRED — must match call.id
  });
}

---

413 / Context Length Exceeded

Error: Maximum context length exceeded

Fix: Trim conversation history, keeping system message:

function trimToFit(messages: any[], maxChars = 100_000): any[] {
  const system = messages.find(m => m.role === 'system');
  const rest = messages.filter(m => m.role !== 'system');
  const kept: any[] = system ? [system] : [];
  let chars = system?.content?.length ?? 0;

  // Keep most recent messages that fit
  for (let i = rest.length - 1; i >= 0; i--) {
    const msgChars = JSON.stringify(rest[i]).length;
    if (chars + msgChars > maxChars) break;
    chars += msgChars;
    kept.splice(system ? 1 : 0, 0, rest[i]);
  }
  return kept;
}

---

500/503 Server Error

Error: Internal server error

Causes: Mistral service issue (temporary).

Fix:

class CircuitBreaker {
  private failures = 0;
  private lastFailure = 0;
  private readonly threshold = 5;
  private readonly resetMs = 60_000;

  async call<T>(fn: () => Promise<T>): Promise<T> {
    if (this.failures >= this.threshold) {
      if (Date.now() - this.lastFailure < this.resetMs) {
        throw new Error('Circuit breaker open — Mistral service unavailable');
      }
      this.failures = 0; // Reset after timeout
    }
    try {
      const result = await fn();
      this.failures = 0;
      return result;
    } catch (error: any) {
      if (error.status >= 500) {
        this.failures++;
        this.lastFailure = Date.now();
      }
      throw error;
    }
  }
}

---

ERR_REQUIRE_ESM (Node.js)

Error [ERR_REQUIRE_ESM]: require() of ES Module not supported

Cause: @mistralai/mistralai is ESM-only since v1.x.

Fix: Either use import syntax (recommended) or dynamic import:

// Option 1: Convert to ESM
// package.json: "type": "module"
import { Mistral } from '@mistralai/mistralai';

// Option 2: Dynamic import in CJS
const { Mistral } = await import('@mistralai/mistralai');

---

Network Timeout

Error: Request timeout after 30000ms

Fix:

const client = new Mistral({
  apiKey: process.env.MISTRAL_API_KEY,
  timeoutMs: 60_000, // Increase for long completions
});

// For streaming, the timeout applies to initial connection
// Individual chunks have no timeout

Escalation Path

1. Collect evidence with mistral-debug-bundle
2. Check status.mistral.ai
3. Contact support via Discord or console.mistral.ai

Error Handling

Error	Cause	Solution
401	Auth failure	Regenerate key at console.mistral.ai
429	Rate limit	Backoff + check tier limits
400	Bad params	Validate model, messages, tools
413	Context overflow	Trim conversation history
5xx	Service error	Retry with circuit breaker
ERR_REQUIRE_ESM	CJS import	Use ESM import syntax

Resources

• Mistral API Reference
• Rate Limits & Tiers
• Status Page
• Discord Community

Next Steps

For comprehensive debugging, see mistral-debug-bundle.