# Common Error Codes in OpenSEO: A Complete Reference for Error Handling

> Learn common OpenSEO error codes for authentication, billing, and API issues. This reference guide details 18 standardized errors to help you implement effective error handling.

- Repository: [Every App/open-seo](https://github.com/every-app/open-seo)
- Tags: api-reference
- Published: 2026-09-01

---

**OpenSEO defines 18 standardized error codes in [`src/shared/error-codes.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/error-codes.ts) that cover authentication failures, billing issues, audit limits, and external API errors, all enforced through a Zod enum schema and thrown via the `AppError` class.**

OpenSEO is an open-source SEO platform that uses a centralized error code system to ensure consistent failure handling across server and client layers. According to the every-app/open-seo source code, these codes are exported as a Zod enum called `errorCodeSchema` and propagated throughout the application via the `AppError` class. Understanding these codes helps developers debug integration issues and handle edge cases gracefully.

## Where OpenSEO Error Codes Are Defined

The canonical list of common error codes in OpenSEO lives in **[`src/shared/error-codes.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/error-codes.ts)**. This file exports `errorCodeSchema`, a Zod enum that type-enforces all valid error strings at runtime.

The schema includes utility functions such as `isErrorCode()` for type guards and `shouldCaptureAppErrorCode()` for telemetry filtering. These utilities ensure that only legitimate error codes defined in the central registry are thrown, preventing typos or inconsistent error handling across the codebase.

## Authentication and Billing Error Codes

OpenSEO separates authentication failures from billing violations to provide clear remediation paths for users.

### UNAUTHENTICATED and AUTH_CONFIG_MISSING

The **`UNAUTHENTICATED`** code triggers when no valid user session or JWT token is present in the request. In self-hosted deployments, **`AUTH_CONFIG_MISSING`** indicates the server cannot locate required authentication settings in its environment configuration.

### PAYMENT_REQUIRED and Feature-Specific Billing Issues

The **`PAYMENT_REQUIRED`** code signals that a user accessed a paid feature without an active subscription. OpenSEO also provides granular billing errors: **`BACKLINKS_BILLING_ISSUE`** and **`AI_SEARCH_BILLING_ISSUE`** indicate payment problems specific to those premium features, allowing the UI to display targeted upgrade prompts.

### INSUFFICIENT_CREDITS and FORBIDDEN

When external provider quotas (such as DataForSEO credits) are exhausted, OpenSEO returns **`INSUFFICIENT_CREDITS`**. Conversely, **`FORBIDDEN`** indicates that an authenticated user lacks the permission scope required for the requested resource, distinguishing between authentication and authorization failures.

## Audit and Resource Limit Error Codes

SEO audit operations have specific concurrency and capacity constraints that generate unique error states.

### Audit Concurrency and Duplicate Prevention

The **`AUDIT_CAPACITY_REACHED`** code indicates a system-wide concurrency limit has been hit, preventing new site audits from starting until existing ones complete. If a client attempts to start an audit while one is already in progress for the same project, OpenSEO returns **`AUDIT_ALREADY_RUNNING`** to prevent duplicate work.

### Page Limits and Validation Failures

When an audit request exceeds the per-project page quota, OpenSEO responds with **`AUDIT_PAGE_LIMIT_EXCEEDED`**. For general input validation failures—such as malformed URLs or invalid JSON payloads—the platform uses **`VALIDATION_ERROR`** to indicate Zod schema validation failures in the request payload.

## Crawling and External API Error Codes

OpenSEO integrates with external services and respects robots.txt directives, generating specific codes when these interactions fail.

### CRAWL_TARGET_BLOCKED and Robots.txt Violations

The **`CRAWL_TARGET_BLOCKED`** error occurs when a target URL explicitly blocks crawling via robots.txt or IP-level bans. This distinguishes permission-based crawl failures from technical errors.

### External Provider Failures

When integrating with DataForSEO or similar providers, OpenSEO surfaces **`DATAFORSEO_AUTH_FAILED`** for invalid API credentials. For downstream service outages, **`UPSTREAM_UNAVAILABLE`** indicates that Google or DataForSEO APIs are unreachable. If rate limits are exceeded on either internal or external APIs, the platform returns **`RATE_LIMITED`**.

### Generic Resource and Internal Errors

For standard HTTP-like semantics, OpenSEO uses **`NOT_FOUND`** for missing entities and **`CONFLICT`** for duplicate creation attempts. The catch-all **`INTERNAL_ERROR`** represents unexpected server failures that do not map to specific known states.

## How to Throw and Handle Errors in OpenSEO

The **`AppError`** class in [`src/server/lib/errors.ts`](https://github.com/every-app/open-seo/blob/main/src/server/lib/errors.ts) provides the primary mechanism for throwing typed errors. It accepts an error code from `errorCodeSchema` and an optional message string.

```typescript
// Throwing a typed error in a server handler
import { AppError } from "@/server/lib/errors";
import { errorCodeSchema } from "@/shared/error-codes";

export async function myHandler(req: Request) {
  const user = await getUser(req);
  if (!user) {
    // UNAUTHENTICATED error will be sent back as a client-friendly message
    throw new AppError("UNAUTHENTICATED");
  }

  if (!hasPaidPlan(user)) {
    // PAYMENT_REQUIRED conveys a billing problem
    throw new AppError("PAYMENT_REQUIRED", "Upgrade required to access this feature");
  }

  // ... normal processing
}

```

To prevent leaking internal error details to clients, use the **`toClientError()`** helper. This function strips stack traces and internal metadata unless the error code is explicitly whitelisted for client exposure.

```typescript
// Converting a server error to a client-safe error
import { toClientError } from "@/server/lib/errors";

try {
  await myHandler(request);
} catch (err) {
  // `toClientError` strips internal details unless the code is whitelisted
  const clientError = toClientError(err);
  // Send the error message back to the front-end
  return new Response(clientError.message, { status: 400 });
}

```

## Summary

- OpenSEO defines 18 standardized error codes in [`src/shared/error-codes.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/error-codes.ts), exported as the Zod enum `errorCodeSchema`.
- Authentication errors (`UNAUTHENTICATED`, `AUTH_CONFIG_MISSING`) are separated from billing errors (`PAYMENT_REQUIRED`, `INSUFFICIENT_CREDITS`) and permission errors (`FORBIDDEN`).
- Audit-specific codes (`AUDIT_CAPACITY_REACHED`, `AUDIT_PAGE_LIMIT_EXCEEDED`) handle concurrency and quota limits for SEO crawling operations.
- External integration failures use specific codes like `DATAFORSEO_AUTH_FAILED` and `UPSTREAM_UNAVAILABLE` to distinguish between credential issues and service outages.
- The `AppError` class in [`src/server/lib/errors.ts`](https://github.com/every-app/open-seo/blob/main/src/server/lib/errors.ts) provides type-safe error throwing, while `toClientError()` sanitizes internal details for frontend consumption.

## Frequently Asked Questions

### What file contains the complete list of OpenSEO error codes?

The complete registry of error codes is located in **[`src/shared/error-codes.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/error-codes.ts)**. This file exports the `errorCodeSchema` Zod enum along with helper utilities like `isErrorCode()` for validating error strings at runtime.

### How does OpenSEO sanitize internal errors for client consumption?

OpenSEO uses the **`toClientError()`** function exported from [`src/server/lib/errors.ts`](https://github.com/every-app/open-seo/blob/main/src/server/lib/errors.ts) to strip internal stack traces and sensitive metadata before sending error responses to the client. This function only preserves whitelisted error codes and generic messages to prevent information leakage.

### What error code indicates a problem with DataForSEO credentials?

The **`DATAFORSEO_AUTH_FAILED`** error code specifically indicates invalid or missing DataForSEO API credentials. This is distinct from **`INSUFFICIENT_CREDITS`**, which indicates valid authentication but exhausted quota limits.

### How do I check if a string is a valid OpenSEO error code?

Import the **`isErrorCode()`** utility from [`src/shared/error-codes.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/error-codes.ts). This function acts as a TypeScript type guard, returning `true` only if the string matches one of the 18 defined error codes in the Zod schema, enabling runtime validation of error strings.