Errors

Vela SDK separates missing configuration, Vela API errors, and unexpected route errors.

Error Classes

Class	Source	Usage
VelaConfigurationError	Missing app credentials, appId mismatch, missing scope env	Show as a setup error
VelaHttpError	Vela API returned non-2xx	Log status and details

Response Helpers

Helper	Purpose
createVelaEnvironmentDiagnosticsResponse()	Return missing env as { error, missingEnv }
createPreparedExecutionFailureResponse()	Convert blocked / deny to a Web JSON response
createPreparedExecutionFailureHttpResponse()	For runtimes that do not use Web Response
createVelaErrorResponse()	Convert unexpected errors to a Web JSON response
createVelaErrorHttpResponse()	For runtimes that do not use Web Response
getErrorMessage()	Normalize unknown error messages

Unexpected Error Response

import { createVelaErrorResponse, getErrorMessage } from "@vel4ai/sdk";

export function toWebResponse(error: unknown): Response {
  return createVelaErrorResponse(error, {
    fallbackMessage: "Vela route failed unexpectedly.",
  });
}

export function toLogMessage(error: unknown): string {
  return getErrorMessage(error, "unknown error");
}

Non-Allow Is Not An Error

blocked and deny are normal control flow, not exceptions. Return prepared.response from prepareExecutionWithResponse() unchanged, and avoid rewriting the reason message too aggressively on the app side.