Errors

What the SDK throws, how its codes relate to HTTP status, and what to retry.

Browser or server Both dev · https://api.dev.oprag.ai

Two error types

Type	Means	Do
`OpragConfigError`	The SDK cannot work as configured — usually an `sk_*` key in a browser. No request was sent.	Fix the configuration. Never retry.
`OpragError`	The request reached the API and was refused. Carries `status` and `code`.	Branch on `code`, then on `status`.

Status to code

Status	`code`	Typically
401	`unauthorized`	Missing, revoked, or wrong-environment key.
402	`plan_cap`	The workspace hit a plan limit.
403	`forbidden`	Origin not allowlisted, no Origin on an embed key, or IP blocked.
429	`rate_limit`	Too many requests. Back off.
503	`service_unavailable`	The service is temporarily unavailable.
anything else	`undefined`	Use `status` directly.

TypeScript

import { OpragError, OpragConfigError } from "@oprag/sdk";

try {
  await oprag.chat.ask({ question });
} catch (err) {
  if (err instanceof OpragConfigError) throw err; // a bug, not a blip

  if (err instanceof OpragError) {
    if (err.code === "rate_limit") return retryWithBackoff();
    if (err.code === "plan_cap") return showUpgradePrompt();
    if (err.code === "forbidden") return reportOriginProblem(err.message);
    console.error(err.status, err.code, err.message);
    return;
  }

  // Not an OpragError: a network failure or an abort. `AbortError` lands here,
  // which is why aborts stay distinguishable from a 429.
  throw err;
}

What each status means at the API level, and what to change, is on API errors.

Ready to ship?

Get started free