Claude-code-plugins-plus-skills openevidence-common-errors

install

source · Clone the upstream repo

git clone https://github.com/jeremylongshore/claude-code-plugins-plus-skills

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/jeremylongshore/claude-code-plugins-plus-skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/plugins/saas-packs/openevidence-pack/skills/openevidence-common-errors" ~/.claude/skills/jeremylongshore-claude-code-plugins-plus-skills-openevidence-common-errors && rm -rf "$T"

manifest: plugins/saas-packs/openevidence-pack/skills/openevidence-common-errors/SKILL.md

OpenEvidence Common Errors

Overview

OpenEvidence provides AI-powered clinical decision support through evidence-based query answering with citation tracking. API integrations involve submitting clinical questions, retrieving evidence summaries, and managing citation references. Common errors include overly broad queries that exceed processing limits, citation-not-found errors when referenced studies are retracted, and timeouts on complex multi-condition queries that trigger deep literature analysis. The DeepConsult mode provides more thorough analysis but consumes 5x the rate limit quota and has a 90-second timeout. This reference covers authentication, query validation, and clinical-specific error patterns.

Error Reference

Code	Message	Cause	Fix
`401`	`Authentication failed`	Invalid or expired API key	Regenerate at OpenEvidence developer portal
`403`	`Organization access denied`	API key not authorized for org	Verify org ID matches the key's assigned organization
`404`	`Citation not found`	Referenced study retracted or removed	Query for updated evidence; citation database refreshes weekly
`408`	`Query timeout`	Complex multi-condition query exceeded 90s limit	Simplify query to single clinical question; avoid compound conditions
`422`	`Query too broad`	Question not specific enough for clinical analysis	Add condition, population, or intervention to narrow scope
`422`	`Non-medical query`	Question not recognized as clinical	Rephrase using medical terminology and clinical context
`429`	`Rate limited`	Exceeded API request quota	Implement backoff; check `Retry-After` header
`503`	`Service unavailable`	DeepConsult queue at capacity	Retry after 60s; consider standard query mode instead

Error Handler

interface OpenEvidenceError {
  code: number;
  message: string;
  category: "auth" | "rate_limit" | "query" | "availability";
}

function classifyOpenEvidenceError(status: number, body: string): OpenEvidenceError {
  if (status === 401 || status === 403) {
    return { code: status, message: body, category: "auth" };
  }
  if (status === 429) {
    return { code: 429, message: "Rate limited", category: "rate_limit" };
  }
  if (status === 503) {
    return { code: 503, message: body, category: "availability" };
  }
  return { code: status, message: body, category: "query" };
}

Debugging Guide

Authentication Errors

OpenEvidence API keys are scoped per organization. A 401 means the key itself is invalid; a 403 means the key is valid but not authorized for the specified org ID. Verify both the

OPENEVIDENCE_API_KEY

and the

org_id

parameter match. Keys are rotated quarterly for compliance -- check expiration date.

Rate Limit Errors

Rate limits vary by plan tier. Standard plans allow 100 queries/hour; enterprise plans have higher limits. DeepConsult queries (longer analysis) consume 5x the rate limit quota of standard queries. Use

Retry-After

header and implement exponential backoff.

Validation Errors

Queries must be clinically relevant and specific. "What causes headaches?" is too broad -- narrow to "What is the first-line treatment for migraine with aura in adults?" Add population, intervention, or comparison to improve query specificity. Non-medical queries are rejected with 422. Citation references use DOI-based identifiers; retracted studies return 404 and should be re-queried for updated evidence.

Error Handling

Scenario	Pattern	Recovery
Query too broad	422 with specificity warning	Add condition + population + intervention details
Citation not found	404 on citation lookup	Re-query for updated evidence; citations refresh weekly
DeepConsult queue full	503 on complex queries	Fall back to standard query mode; retry deep after delay
Timeout on compound query	408 after 90s	Split into individual clinical questions
Org access mismatch	403 despite valid key	Verify org_id parameter matches key's assigned organization

Quick Diagnostic

# Verify API connectivity and key validity
curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer $OPENEVIDENCE_API_KEY" \
  https://api.openevidence.com/v1/health

Resources

Next Steps

See

openevidence-debug-bundle