dimah-formv0.6.1
Reference

Errors

Stable error codes, field issues, and the errors helper.

Failed requests return JSON { message, code?, params?, issues? } and an HTTP status.

Throw with errors from @dimah-form/server. A plain Error has no stable code.

import {
  APIError,
  FORM_ERROR_CODES,
  errors,
  isAPIError,
} from "@dimah-form/server";

throw errors.unknownForm(formId);
throw errors.unknownResponse(responseId);
throw errors.staleUpdate();
throw errors.formInactive(formId);
throw errors.responseNotDraft(responseId);
throw errors.responseNotLocked(responseId);
throw errors.codeAuthoredForm(formId);
throw errors.formHasResponses(formId);
throw errors.slugTaken(slug);
throw errors.unknownFieldType(type);
throw errors.resumeRequiresRespondent();
throw errors.validationError();
throw errors.validationError(issues);
throw errors.notFound();
throw errors.internalError();

throw APIError.from("UNAUTHORIZED", FORM_ERROR_CODES.UNAUTHORIZED);
throw APIError.from("FORBIDDEN", FORM_ERROR_CODES.FORBIDDEN);
if (isAPIError(err)) {
  console.log(err.code, err.message);
}

isFormErrorCode(err, "STALE_UPDATE") narrows a catalog code. It is exported from @dimah-form/server and @dimah-form/react.

Catalog

codeHTTPWhen
NOT_FOUND404Path matches no route
UNKNOWN_FORM404Id or slug is not in the catalog or the database
UNKNOWN_RESPONSE404Response id is missing
UNAUTHORIZED401Your guard rejected an anonymous caller
FORBIDDEN403Your guard rejected the caller
CONFLICT409Generic conflict code. Core routes use a specific code below
STALE_UPDATE409updatedAt does not match the stored row
FORM_INACTIVE409startResponse on a form that is not "active"
RESPONSE_NOT_DRAFT409Draft write on a locked row
RESPONSE_NOT_LOCKED409reopenResponse on a draft
CODE_AUTHORED_FORM409saveForm or deleteForm on a code form
FORM_HAS_RESPONSES409deleteForm while responses exist
SLUG_TAKEN409Slug already used
VALIDATION_ERROR400Payload or answers failed. Read issues
UNKNOWN_FIELD_TYPE400Field type is not registered
RESUME_REQUIRES_RESPONDENT400resume: true without respondentId
INTERNAL_ERROR500Unhandled exception

Field issues

issues[] on VALIDATION_ERROR. useFormResponse copies these onto issueCodes / binding.errorCode.

codeWhenparams
REQUIREDVisible required field was empty—
UNKNOWN_FIELDAnswer key is not on the snapshot—
UNKNOWN_FIELD_TYPENo validator for field.type{ type }
INVALIDA custom check rejected the value—
EXPECTED_STRINGNot a string—
EXPECTED_NUMBERNot a finite number—
EXPECTED_INTEGERinteger: true and the value is not an integer—
EXPECTED_BOOLEANNot a boolean—
EXPECTED_STRING_ARRAYNot an array of strings—
EXPECTED_EMAILNot an email—
EXPECTED_DATENot YYYY-MM-DD—
EXPECTED_FILENot file metadata—
TOO_SHORT / TOO_LONGminLength / maxLength{ min } / { max }
TOO_SMALL / TOO_LARGEmin / max{ min } / { max }
INVALID_FORMATpattern did not match—
INVALID_OPTIONValue is not in options—
DUPLICATE_OPTIONmultiSelect repeats a value—

English message is the fallback. Localize from code and params.

Scoring

@dimah-form/scoring merges these onto form.$ERROR_CODES. They show up from validateDefinition / saveForm, and from scoreResponse when the mapping is invalid.

codeWhen
SCORING_INVALID_METAmeta.scoring failed its schema
SCORING_FORM_REQUIREDField or option scoring without form meta.scoring
SCORING_UNKNOWN_VARIABLEField or option.add names an id not in variables
SCORING_UNUSED_VARIABLEA declared variable is never mapped
SCORING_DUPLICATE_VARIABLETwo variables share an id
SCORING_DUPLICATE_FORMULAFormula id collides with a variable or another formula
SCORING_UNSUPPORTED_TYPEScoring on a type other than select, multiSelect, number, or boolean
SCORING_MISSING_POINTSLikert option has no points
SCORING_OPTION_ADD_MIXfield.variable together with option.add
SCORING_OPTION_POINTS_NEED_VARIABLEoption.points without field.variable
SCORING_REVERSE_RANGEreverse without a point range
SCORING_REVERSE_MULTISELECTreverse on multiSelect
SCORING_UNKNOWN_BAND_VARIABLEBand variable is not a variable or formula id
SCORING_FORMULA_UNKNOWN_VARFormula vars names a non-variable
SCORING_FORMULA_DUPLICATE_VARFormula vars repeats an id
SCORING_INVALID_BANDBand from is greater than to

Plugin codes

import { defineErrorCodes } from "@dimah-form/server";

export const BILLING_ERROR_CODES = defineErrorCodes({
  PAYMENT_REQUIRED: "Payment verification failed",
});

Attach the same catalog on the server plugin and the client plugin. Codes cannot shadow core or another plugin.

Frequently asked questions

On this page