Cohere Common Errors
Overview
Quick reference for real Cohere API v2 errors with exact messages, causes, and fixes.
Prerequisites
cohere-ai SDK installedCO_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:
await cohere.chat({ messages: [...] });
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'],
});
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:
echo $CO_API_KEY
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) {
await new Promise(r => setTimeout(r, 60_000));
}
}
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: [
{ 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,
});
Diagnostic Commands
curl -s https://status.cohere.com/api/v2/status.json | jq '.status'
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"}]}'
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
Next Steps
For comprehensive debugging, see cohere-debug-bundle.
