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
code | HTTP | When |
|---|---|---|
NOT_FOUND | 404 | Path matches no route |
UNKNOWN_FORM | 404 | Id or slug is not in the catalog or the database |
UNKNOWN_RESPONSE | 404 | Response id is missing |
UNAUTHORIZED | 401 | Your guard rejected an anonymous caller |
FORBIDDEN | 403 | Your guard rejected the caller |
CONFLICT | 409 | Generic conflict code. Core routes use a specific code below |
STALE_UPDATE | 409 | updatedAt does not match the stored row |
FORM_INACTIVE | 409 | startResponse on a form that is not "active" |
RESPONSE_NOT_DRAFT | 409 | Draft write on a locked row |
RESPONSE_NOT_LOCKED | 409 | reopenResponse on a draft |
CODE_AUTHORED_FORM | 409 | saveForm or deleteForm on a code form |
FORM_HAS_RESPONSES | 409 | deleteForm while responses exist |
SLUG_TAKEN | 409 | Slug already used |
VALIDATION_ERROR | 400 | Payload or answers failed. Read issues |
UNKNOWN_FIELD_TYPE | 400 | Field type is not registered |
RESUME_REQUIRES_RESPONDENT | 400 | resume: true without respondentId |
INTERNAL_ERROR | 500 | Unhandled exception |
Field issues
issues[] on VALIDATION_ERROR. useFormResponse copies these onto issueCodes / binding.errorCode.
code | When | params |
|---|---|---|
REQUIRED | Visible required field was empty | — |
UNKNOWN_FIELD | Answer key is not on the snapshot | — |
UNKNOWN_FIELD_TYPE | No validator for field.type | { type } |
INVALID | A custom check rejected the value | — |
EXPECTED_STRING | Not a string | — |
EXPECTED_NUMBER | Not a finite number | — |
EXPECTED_INTEGER | integer: true and the value is not an integer | — |
EXPECTED_BOOLEAN | Not a boolean | — |
EXPECTED_STRING_ARRAY | Not an array of strings | — |
EXPECTED_EMAIL | Not an email | — |
EXPECTED_DATE | Not YYYY-MM-DD | — |
EXPECTED_FILE | Not file metadata | — |
TOO_SHORT / TOO_LONG | minLength / maxLength | { min } / { max } |
TOO_SMALL / TOO_LARGE | min / max | { min } / { max } |
INVALID_FORMAT | pattern did not match | — |
INVALID_OPTION | Value is not in options | — |
DUPLICATE_OPTION | multiSelect 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.
code | When |
|---|---|
SCORING_INVALID_META | meta.scoring failed its schema |
SCORING_FORM_REQUIRED | Field or option scoring without form meta.scoring |
SCORING_UNKNOWN_VARIABLE | Field or option.add names an id not in variables |
SCORING_UNUSED_VARIABLE | A declared variable is never mapped |
SCORING_DUPLICATE_VARIABLE | Two variables share an id |
SCORING_DUPLICATE_FORMULA | Formula id collides with a variable or another formula |
SCORING_UNSUPPORTED_TYPE | Scoring on a type other than select, multiSelect, number, or boolean |
SCORING_MISSING_POINTS | Likert option has no points |
SCORING_OPTION_ADD_MIX | field.variable together with option.add |
SCORING_OPTION_POINTS_NEED_VARIABLE | option.points without field.variable |
SCORING_REVERSE_RANGE | reverse without a point range |
SCORING_REVERSE_MULTISELECT | reverse on multiSelect |
SCORING_UNKNOWN_BAND_VARIABLE | Band variable is not a variable or formula id |
SCORING_FORMULA_UNKNOWN_VAR | Formula vars names a non-variable |
SCORING_FORMULA_DUPLICATE_VAR | Formula vars repeats an id |
SCORING_INVALID_BAND | Band 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
binding.error is English. For your own copy, switch on binding.errorCode:
import {
fieldIssueMap,
formErrorMessage,
issuesByField,
} from "@dimah-form/react";
const messages = issuesByField(error); // { fullName: "Full name is required" }
const issues = fieldIssueMap(error); // { fullName: { field, message, code, params } }
const message = formErrorMessage(error);@dimah-form/ui uses formatIssue on FormUiProvider for the same map.
useFormResponse refreshes on STALE_UPDATE. Handle it yourself when you call formClient.saveDraft outside the hook.