upstash/context7 · error · Context7Error

errorBody.error ?? "http_error"

errorBody.error ?? "http_error"

Error message

errorBody.message || errorBody.error || response.statusText

What it means

Context7Error thrown by throwResponseError when the server returns a non-OK HTTP response. The message comes from the error body's `message` or `error` field, falling back to response.statusText; the code comes from the body's `error` field, falling back to "http_error". Status, requestId, and rate-limit info are attached.

Source

Thrown at packages/sdk/src/http/response.ts:78

  if (rawBody) {
    try {
      const parsed: unknown = JSON.parse(rawBody);
      if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
        const { error, message } = parsed as Record<string, unknown>;
        errorBody = {
          error: typeof error === "string" ? error : undefined,
          message: typeof message === "string" ? message : undefined,
        };
      }
    } catch (cause) {
      if (response.headers.get("content-type")?.includes("application/json")) {
        throw jsonParseError(rawBody, metadata, cause, retryable);
      }
    }
  }

  throw new Context7Error(errorBody.message || errorBody.error || response.statusText, {
    code: errorBody.error ?? "http_error",
    status: response.status,
    requestId: metadata.requestId,
    rateLimit: metadata.rateLimit,
    retryable,
  });
}

async function parseJson(response: Response, metadata: Context7ResponseMetadata): Promise<unknown> {
  const rawBody = await response.text();
  try {
    return JSON.parse(rawBody);
  } catch (cause) {
    throw jsonParseError(rawBody, metadata, cause, false);
  }
}

function jsonParseError(

View on GitHub (pinned to 80e681a507)

Solutions

1. Read err.status and err.code to branch: 401 -> fix credentials, 429 -> back off (use err.rateLimit), 404 -> verify the library id, 5xx -> retry later.
2. Check err.rateLimit headers to implement client-side rate limiting before the 429 occurs.
3. Verify your API key is valid and set correctly for authenticated endpoints.
4. Confirm the library/topic ids passed to queries exist (e.g. list/search first).

Example fix

// before
const res = await client.getLibraryDocs('/websites/react'); // 404 -> Context7Error 'http_error'
// after
try {
  const res = await client.getLibraryDocs('/websites/react');
} catch (e) {
  if (e instanceof Context7Error && e.status === 429) {
    await sleep(e.rateLimit?.resetMs ?? 60000);
  } else throw e;
}

// Validate inputs the API is known to 404 on
if (!libraryId.startsWith('/')) throw new Error(`libraryId should look like '/websites/react', got: ${libraryId}`);

function isHttpApiError(e: unknown): e is Context7Error & { status: number } {
  return e instanceof Context7Error && typeof (e as any).status === 'number';
}

try {
  return await client.getLibraryDocs(id);
} catch (e) {
  if (isHttpApiError(e)) {
    if (e.status === 429) return await retryAfterBackoff(e.rateLimit);
    if (e.status === 401) throw new Error('Check your Context7 API key');
    if (e.status === 404) throw new Error(`Unknown library: ${id}`);
  }
  throw e;
}

When it happens

Trigger: Any request receiving 4xx/5xx: 401 invalid API key, 404 unknown library id, 429 rate limited (code often 'rate_limit'), 500 server errors — whenever the body is not JSON or lacks the fields, message falls back to statusText.

Common situations: Expired or wrong API key (401), hitting rate limits (429), requesting a non-existent Context7 library id (404), upstream server outages (5xx).

Understand the failure class

Background: "API error: {status}" and "HTTP 401/403/404/429/5xx" errors: non-2xx HTTP responses explained — this error's family across 27 libraries.

Related errors

• errorBody.error || errorBody.message || res.statusText
• Failed to fetch ${item.path}: ${fileResponse.status}
• await describeErrorResponse(response, fallback)
• Port ${port} is in use, trying port ${port + 1}...
• invalid_response

AI-assisted analysis of upstash/context7@80e681a507 (2026-09-08). Data as JSON: /api/errors/277222f6719529aa. Report an issue: GitHub.