# Jeremylongshore Claude Code Plugins Plus Skills Mistral Common Errors > Mistral AI Common Errors - Skill: `tomevault-io/jeremylongshore-claude-code-plugins-plus-skills-mistral-comm` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/jeremylongshore-claude-code-plugins-plus-skills-mistral-comm` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/jeremylongshore-claude-code-plugins-plus-skills-mistral-comm/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/jeremylongshore-claude-code-plugins-plus-skills-mistral-comm --- # 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 ```bash 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:** ```typescript 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:** ```bash 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:** ```typescript async function withBackoff(fn: () => Promise, maxRetries = 5): Promise { 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](https://admin.mistral.ai/plateforme/limits) for workspace RPM/TPM caps. --- #### 400 Bad Request — Invalid Model ``` {"message": "Unknown model: mistral-ultra"} ``` **Fix:** Use valid model IDs: ```typescript 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:** ```bash 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: ```typescript 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`: ```typescript // 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: ```typescript 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:** ```typescript class CircuitBreaker { private failures = 0; private lastFailure = 0; private readonly threshold = 5; private readonly resetMs = 60_000; async call(fn: () => Promise): Promise { 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: ```typescript // 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:** ```typescript 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](https://status.mistral.ai/) 3. Contact support via [Discord](https://discord.gg/mistralai) 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](https://docs.mistral.ai/api/) - [Rate Limits & Tiers](https://docs.mistral.ai/deployment/ai-studio/tier/) - [Status Page](https://status.mistral.ai/) - [Discord Community](https://discord.gg/mistralai) ## Next Steps For comprehensive debugging, see `mistral-debug-bundle`. --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/jeremylongshore) — claim your Tome and manage your conversions.