MiMo-V2.5 API Error? 401, 429 and Timeout Fixes (2026)

Xiaomi mimo-v2 API Error: Complete Troubleshooting Guide

🔄 Updated 2026-09-17

The error taxonomy below has not changed, but the model facts have: MiMo-V2.5 is a paid OpenRouter model now, so the 401 / 429 / 408 fixes assume you are calling the current ID.

• Verify ID, price and context: MiMo-V2.5 model page.
• Choosing a fallback when the endpoint is saturated: comparison hub and the pricing calculator.

Quick Answer

Most mimo-v2 API errors fall into 4 categories:

Authentication Errors (401 Unauthorized)

Error Message

{
  "error": {
    "message": "Invalid API key",
    "code": 401
  }
}

Causes

1. API key is incorrect or malformed
2. API key has been revoked
3. API key not included in headers
4. Using wrong header format

Solution

Step 1: Verify API key format

OpenRouter API keys look like:

sk-or-v1-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Step 2: Check header format

// Correct
headers: {
  'Authorization': 'Bearer sk-or-v1-xxxx',
  'Content-Type': 'application/json',
}

// Wrong - missing "Bearer"
headers: {
  'Authorization': 'sk-or-v1-xxxx',  // ❌
}

// Wrong - wrong header name
headers: {
  'API-Key': 'sk-or-v1-xxxx',  // ❌
}

Step 3: Regenerate API key

1. Go to OpenRouter settings
2. Click “Regenerate API Key”
3. Update your environment variables

Step 4: Check environment variables

# .env.local
OPENROUTER_API_KEY=sk-or-v1-xxxx

# In your code
const apiKey = process.env.OPENROUTER_API_KEY;
if (!apiKey) {
  console.error('API key not found!');
}

Rate Limit Errors (429 Too Many Requests)

Error Message

{
  "error": {
    "message": "Rate limit exceeded",
    "code": 429,
    "retry_after": 60
  }
}

Solution

Implement exponential backoff:

async function callWithRetry(prompt, maxRetries = 3) {
  let lastError;

  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch('https://openrouter.ai/api/v1/chat/completions', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${process.env.OPENROUTER_API_KEY}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          model: 'xiaomi/mimo-v2',
          messages: [{ role: 'user', content: prompt }],
          max_tokens: 4096,
        }),
      });

      if (response.status === 429) {
        const data = await response.json();
        const retryAfter = data.error?.retry_after || Math.pow(2, attempt);

        console.log(`Rate limited. Retrying in ${retryAfter}s...`);
        await new Promise(r => setTimeout(r, retryAfter * 1000));
        continue;
      }

      return await response.json();

    } catch (error) {
      lastError = error;
      console.error(`Attempt ${attempt} failed:`, error);
    }
  }

  throw lastError;
}

Reduce request frequency:

• Batch multiple questions into single requests
• Use smaller context sizes to reduce processing time
• Implement request queuing

Timeout Errors (408/504)

Error Message

{
  "error": {
    "message": "Request timeout",
    "code": 408
  }
}

or

{
  "error": {
    "message": "Gateway timeout",
    "code": 504
  }
}

Causes

1. Context too large (>500K tokens)
2. Server under heavy load
3. Network connectivity issues
4. Request processing exceeds time limit

Solution

Reduce context size:

// Instead of sending entire document
const fullDocument = await readMassiveFile(); // 800K tokens

// Send in chunks
const chunks = splitIntoChunks(fullDocument, 100000); // 100K each
for (const chunk of chunks) {
  const summary = await callHunterAlpha(`Summarize: ${chunk}`);
  summaries.push(summary);
}

// Final synthesis
const result = await callHunterAlpha(`Combine: ${summaries.join('\n')}`);

Increase timeout settings:

// With fetch
const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 120000); // 2 minutes

const response = await fetch('https://openrouter.ai/api/v1/chat/completions', {
  method: 'POST',
  signal: controller.signal,
  headers: { ... },
  body: JSON.stringify({ ... }),
});

clearTimeout(timeoutId);

Bad Request Errors (400)

Error Message

{
  "error": {
    "message": "Invalid request format",
    "code": 400
  }
}

Common Causes

1. Malformed JSON

// Wrong - missing quotes
body: JSON.stringify({
  model: xiaomi/mimo-v2,  // ❌ Should be string
})

// Correct
body: JSON.stringify({
  model: "xiaomi/mimo-v2",  // ✅
})

2. Invalid message structure

// Wrong
messages: [
  { role: "human", content: "Hello" },  // ❌ Should be "user"
]

// Correct
messages: [
  { role: "user", content: "Hello" },  // ✅
  { role: "assistant", content: "Hi!" },
  { role: "user", content: "How are you?" },
]

3. Missing required fields

// Wrong - missing model
body: JSON.stringify({
  messages: [...],  // ❌
})

// Correct
body: JSON.stringify({
  model: "xiaomi/mimo-v2",  // ✅
  messages: [...],
})

Response Parsing Errors

Symptoms

• API call succeeds but code crashes
• undefined when accessing response fields
• TypeError on response data

Solution

Always validate response structure:

async function safeCall(prompt) {
  try {
    const response = await fetch('...', { ... });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.error?.message || 'Unknown error');
    }

    const data = await response.json();

    // Validate structure
    if (!data.choices?.[0]?.message?.content) {
      console.warn('Unexpected response format:', data);
      return null;
    }

    return data.choices[0].message.content;

  } catch (error) {
    console.error('API call failed:', error);
    throw error;
  }
}

Debugging Checklist

When you encounter an API error:

• Verify API key is valid and not expired
• Check HTTP status code (401, 429, 400, 408, 504)
• Inspect request headers (Authorization format)
• Validate JSON payload structure
• Check context size (tokens used)
• Review server logs for detailed error messages
• Test with minimal request (hello world)
• Try from different network/browser

Useful Tools

API Testing:

• OpenRouter Playground
• Postman
• curl

Debugging Code:

async function debugApiCall(prompt) {
  console.log('=== API Request Debug ===');
  console.log('Prompt length:', prompt.length);
  console.log('Estimated tokens:', Math.ceil(prompt.length / 4));

  const startTime = Date.now();

  try {
    const response = await fetch('...', { ... });
    const endTime = Date.now();

    console.log('Response time:', endTime - startTime, 'ms');
    console.log('Status:', response.status, response.statusText);
    console.log('Headers:', Object.fromEntries(response.headers));

    const data = await response.json();
    console.log('Response:', JSON.stringify(data, null, 2));

    return data;
  } catch (error) {
    console.error('Error:', error);
    throw error;
  }
}

Need more help? The failure modes we can name are on Union Alpha not working.