mastra-ai/mastra · error

Cohere API error: ${response.status} ${await response.text()

Error message

Cohere API error: ${response.status} ${await response.text()}

What it means

After calling the Cohere /v2/rerank endpoint, any non-OK HTTP status causes this error, embedding the status code and the raw response body. It signals the request failed upstream (auth, billing, bad model name, rate limiting, malformed request).

Source

Thrown at packages/rag/src/rerank/relevance/cohere/index.ts:48

      throw new Error('Cohere API key is required. Pass an apiKey or set COHERE_API_KEY.');
    }

    const response = await fetch(`https://api.cohere.com/v2/rerank`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${this.apiKey}`,
      },
      body: JSON.stringify({
        query,
        documents: [text],
        model: this.model,
        top_n: 1,
      }),
    });

    if (!response.ok) {
      throw new Error(`Cohere API error: ${response.status} ${await response.text()}`);
    }

    const data = (await response.json()) as CohereRerankingResponse;
    const relevanceScore = data.results[0]?.relevance_score;

    if (typeof relevanceScore !== 'number' || !Number.isFinite(relevanceScore)) {
      throw new Error('No relevance score found on Cohere response');
    }

    return relevanceScore;
  }
}

View on GitHub (pinned to 75dd419e61)

Solutions

1. Read the status and body in the error message: 401/403 -> fix the API key, 429 -> back off and retry, 400 -> check model and payload
2. Verify the API key is valid and has rerank access in the Cohere dashboard
3. Retry with exponential backoff on 429/5xx transient failures

Example fix

// before
const score = await reranker.getRelevanceScore(query, text); // throws on 429
// after
try {
  const score = await reranker.getRelevanceScore(query, text);
} catch (e) {
  if (String(e.message).includes('429')) await sleep(backoff);
  else throw e;
}

// Nothing to check pre-call besides the key; optionally preflight:
const ok = Boolean(process.env.COHERE_API_KEY);

try { return await reranker.getRelevanceScore(q, t); } catch (e) {
  const m = /Cohere API error: (\d+)/.exec(e.message);
  if (m && (m[1] === '429' || m[1].startsWith('5'))) return retryWithBackoff();
  throw e;
}

When it happens

Trigger: Calling getRelevanceScore with an invalid/expired API key (401), unknown model (400/404), exhausted quota (429), or network/gateway errors (5xx).

Common situations: Using a model name not available to the account; expired or revoked key; rate limits hit under load; Cohere API deprecations requiring a newer rerank model version.

Related errors

• No relevance score found on Cohere response
• Token exchange failed: ${error}
• Google Directory groups.list failed (${response.status}): ${
• skill_invocation_failed
• HTTP_ERROR

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/f5575e91133b59cd. Report an issue: GitHub.