cohere-common-errors

Cohere Common Errors

Overview

Quick reference for real Cohere API v2 errors with exact messages, causes, and fixes.

Prerequisites

• cohere-ai SDK installed
• CO_API_KEY configured
• Access to error logs

Error Reference

400 — Bad Request: Missing Required Field

CohereError: model is required

Cause: API v2 requires model for all endpoints (Chat, Embed, Rerank, Classify).

Fix:

// Wrong (v1 style)
await cohere.chat({ messages: [...] });

// Correct (v2)
await cohere.chat({ model: 'command-a-03-2025', messages: [...] });

---

400 — Embed: Missing embedding_types

CohereError: embedding_types is required for embed models v3 and higher

Fix:

await cohere.embed({
  model: 'embed-v4.0',
  texts: ['hello'],
  inputType: 'search_document',
  embeddingTypes: ['float'],  // Required for v3+
});

---

400 — Embed: Missing input_type

CohereError: input_type is required for embed models v3 and higher

Fix: Use one of: search_document, search_query, classification, clustering, image.

---

401 — Invalid API Token

CohereError: invalid api token

Cause: CO_API_KEY is missing, wrong, or revoked.

Fix:

# Verify key is set
echo $CO_API_KEY

# Test directly
curl -H "Authorization: Bearer $CO_API_KEY" \
  https://api.cohere.com/v2/chat \
  -H "Content-Type: application/json" \
  -d '{"model":"command-r7b-12-2024","messages":[{"role":"user","content":"hi"}]}'

---

429 — Rate Limit Exceeded

CohereError: You are using a Trial key, which is limited to N calls/minute

Rate limits by key type:

Key Type	Chat	Embed	Rerank	Other
Trial	20/min	5/min	5/min	1000/month
Production	1000/min	1000/min	1000/min	Unlimited

Fix:

import { CohereError } from 'cohere-ai';

try {
  await cohere.chat({ model: 'command-a-03-2025', messages: [...] });
} catch (err) {
  if (err instanceof CohereError && err.statusCode === 429) {
    // Back off and retry
    await new Promise(r => setTimeout(r, 60_000)); // wait 60s for trial keys
    // retry...
  }
}

---

400 — Classify: Too Few Examples

CohereError: each unique label requires at least 2 examples

Fix:

await cohere.classify({
  model: 'embed-english-v3.0',
  inputs: ['This product is amazing'],
  examples: [
    // Need at least 2 examples PER label
    { text: 'I love it', label: 'positive' },
    { text: 'Great product', label: 'positive' },
    { text: 'Terrible', label: 'negative' },
    { text: 'Worst ever', label: 'negative' },
  ],
});

---

400 — Rerank: Too Many Documents

CohereError: too many documents, max is 1000

Fix: Batch your documents:

async function batchRerank(query: string, docs: string[], topN = 10) {
  const BATCH = 1000;
  let allResults: any[] = [];

  for (let i = 0; i < docs.length; i += BATCH) {
    const batch = docs.slice(i, i + BATCH);
    const resp = await cohere.rerank({
      model: 'rerank-v3.5',
      query,
      documents: batch,
      topN,
    });
    allResults.push(
      ...resp.results.map(r => ({ ...r, index: r.index + i }))
    );
  }

  return allResults.sort((a, b) => b.relevanceScore - a.relevanceScore).slice(0, topN);
}

---

400 — Chat: response_format with documents

CohereError: response_format is not supported with documents or tools

Cause: response_format: { type: 'json_object' } cannot be combined with documents or tools.

Fix: Use either JSON mode OR document/tool mode, not both. For structured RAG output, parse the text response yourself.

---

500/503 — Server Error

CohereError: internal server error

Fix: Retry with exponential backoff. If persistent, check status.cohere.com.

---

CohereTimeoutError

CohereTimeoutError: Request timed out

Fix: The SDK has a default timeout. Increase it or reduce payload:

const cohere = new CohereClientV2({
  token: process.env.CO_API_KEY,
  timeoutInSeconds: 120, // default is lower
});

Diagnostic Commands

# Check Cohere service status
curl -s https://status.cohere.com/api/v2/status.json | jq '.status'

# Verify API key works
curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer $CO_API_KEY" \
  https://api.cohere.com/v2/chat \
  -H "Content-Type: application/json" \
  -d '{"model":"command-r7b-12-2024","messages":[{"role":"user","content":"ping"}]}'

# Check installed SDK version
npm list cohere-ai 2>/dev/null || pip show cohere 2>/dev/null

Error Handling Wrapper

import { CohereError, CohereTimeoutError } from 'cohere-ai';

function diagnoseCohereError(err: unknown): string {
  if (err instanceof CohereTimeoutError) {
    return 'TIMEOUT: Increase timeoutInSeconds or reduce input size';
  }
  if (err instanceof CohereError) {
    switch (err.statusCode) {
      case 400: return `BAD_REQUEST: ${err.message}`;
      case 401: return 'AUTH: Check CO_API_KEY';
      case 429: return 'RATE_LIMIT: Back off or upgrade key';
      case 500: return 'SERVER: Retry later, check status.cohere.com';
      default:  return `UNKNOWN (${err.statusCode}): ${err.message}`;
    }
  }
  return `UNEXPECTED: ${String(err)}`;
}

Resources

• Cohere Error Codes
• Cohere Status Page
• Rate Limits
• API v1 to v2 Migration

Next Steps

For comprehensive debugging, see cohere-debug-bundle.