{"record":{"id":"f5575e91133b59cd","repo":"mastra-ai/mastra","slug":"cohere-api-error-response-status-await-respo","errorCode":null,"errorMessage":"Cohere API error: ${response.status} ${await response.text()}","messagePattern":"Cohere API error: (.+?) (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/rag/src/rerank/relevance/cohere/index.ts","lineNumber":48,"sourceCode":"      throw new Error('Cohere API key is required. Pass an apiKey or set COHERE_API_KEY.');\n    }\n\n    const response = await fetch(`https://api.cohere.com/v2/rerank`, {\n      method: 'POST',\n      headers: {\n        'Content-Type': 'application/json',\n        Authorization: `Bearer ${this.apiKey}`,\n      },\n      body: JSON.stringify({\n        query,\n        documents: [text],\n        model: this.model,\n        top_n: 1,\n      }),\n    });\n\n    if (!response.ok) {\n      throw new Error(`Cohere API error: ${response.status} ${await response.text()}`);\n    }\n\n    const data = (await response.json()) as CohereRerankingResponse;\n    const relevanceScore = data.results[0]?.relevance_score;\n\n    if (typeof relevanceScore !== 'number' || !Number.isFinite(relevanceScore)) {\n      throw new Error('No relevance score found on Cohere response');\n    }\n\n    return relevanceScore;\n  }\n}\n","sourceCodeStart":30,"sourceCodeEnd":61,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/rag/src/rerank/relevance/cohere/index.ts#L30-L61","documentation":"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).","triggerScenarios":"Calling getRelevanceScore with an invalid/expired API key (401), unknown model (400/404), exhausted quota (429), or network/gateway errors (5xx).","commonSituations":"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.","solutions":["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","Verify the API key is valid and has rerank access in the Cohere dashboard","Retry with exponential backoff on 429/5xx transient failures"],"exampleFix":"// before\nconst score = await reranker.getRelevanceScore(query, text); // throws on 429\n// after\ntry {\n  const score = await reranker.getRelevanceScore(query, text);\n} catch (e) {\n  if (String(e.message).includes('429')) await sleep(backoff);\n  else throw e;\n}","handlingStrategy":"retry","validationCode":"// Nothing to check pre-call besides the key; optionally preflight:\nconst ok = Boolean(process.env.COHERE_API_KEY);","typeGuard":null,"tryCatchPattern":"try { return await reranker.getRelevanceScore(q, t); } catch (e) {\n  const m = /Cohere API error: (\\d+)/.exec(e.message);\n  if (m && (m[1] === '429' || m[1].startsWith('5'))) return retryWithBackoff();\n  throw e;\n}","preventionTips":["Retry 429/5xx with exponential backoff; never retry 4xx auth errors","Pin a supported rerank model name and update on deprecation notices","Monitor Cohere status/quota for the account"],"tags":["network","api-error","cohere","rerank"],"backgroundTag":"upstream-api-error","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}