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

OpenSEO defines 18 standardized error codes in 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. 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 provides the primary mechanism for throwing typed errors. It accepts an error code from errorCodeSchema and an optional message string.

// 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.

// 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, 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 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. 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 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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}