Server Error Reconciliation

Client-side validation is a courtesy. The server’s rejection is the fact. Every form eventually has to render a failure it could not have predicted — an address that is already registered, a coupon that expired between page load and submit, a business rule that only the server can evaluate — and the machinery for that is different from the machinery for “this field is empty”.

Problem Statement

The specific sub-problem is attribution over time. A local validation error is a pure function of the current value, so it is always current: change the value and it is recomputed. A server error is a snapshot of a judgement made about one particular payload at one particular moment. It cannot be recomputed locally, it may be stale the instant the reader types, and there is no rule that says when it stops being true.

That difference produces four requirements that a form built only for local validation does not meet:

• Every server error needs an origin and a subject. Which field, and what value was rejected. Without the value, there is no way to decide when the error stops applying.
• Server errors must not be cleared by the same trigger that clears local ones. A keystroke invalidates a local rule; it does not invalidate a server judgement.
• Some server errors belong to no field at all. “Your session expired” and “this order can no longer be modified” have no input to sit beside.
• Rejections are not all validation. A 500 and a 422 both fail the submit, and treating them the same tells the reader their input was wrong when the truth is that your service was.

State Machine Specification

The submission’s outcome fans out into four handling paths, and conflating any two of them produces a recognisable bug.

The last row is the one most often collapsed into the second. Marking fields invalid because a gateway timed out blocks a submit the server would have accepted, and it tells the reader they made a mistake they did not make.

Core Implementation

The reconciler is a pure function from a response to a set of state changes. Keeping it pure is what makes the five rows above testable against captured payloads rather than against a running server.

interface ServerFieldError {
  readonly field: string;          // canonical dotted path, matching the rendered name
  readonly message: string;        // shown as-is; the server owns this wording
  readonly code: string;           // stable identifier for analytics and for tests
  /** The exact value that was rejected. This is what makes clearing possible. */
  readonly rejectedValue: unknown;
  readonly origin: 'server';
}

type SubmitOutcome =
  | { kind: 'accepted'; record: unknown }
  | { kind: 'field-errors'; errors: ServerFieldError[] }
  | { kind: 'form-error'; message: string; code: string; retryable: boolean }
  | { kind: 'conflict'; remoteVersion: string }
  | { kind: 'unavailable'; retryAfterMs: number | null };

export function reconcile(res: Response, body: unknown, sent: Record<string, unknown>): SubmitOutcome {
  if (res.ok) return { kind: 'accepted', record: body };

  if (res.status === 409) {
    return { kind: 'conflict', remoteVersion: String((body as any)?.version ?? '') };
  }

  if (res.status === 422 && Array.isArray((body as any)?.errors)) {
    const errors: ServerFieldError[] = [];
    for (const raw of (body as any).errors as any[]) {
      const field = toCanonicalPath(raw.pointer ?? raw.field ?? '');
      // An error we cannot attach to a rendered field must NOT be dropped —
      // it becomes a form-level message instead, or the submit fails silently.
      if (!field) continue;
      errors.push({
        field,
        message: String(raw.detail ?? raw.message ?? 'This value was not accepted'),
        code: String(raw.code ?? 'server_rejected'),
        // Capture what was sent, not what is in the field now: the reader may
        // already have typed something else while the request was in flight.
        rejectedValue: valueAt(sent, field),
        origin: 'server',
      });
    }
    if (errors.length > 0) return { kind: 'field-errors', errors };
  }

  if (res.status >= 500 || res.status === 408) {
    const header = res.headers.get('retry-after');
    return { kind: 'unavailable', retryAfterMs: header ? Number(header) * 1000 : null };
  }

  return {
    kind: 'form-error',
    message: String((body as any)?.detail ?? 'We could not submit this form.'),
    code: String((body as any)?.code ?? `http_${res.status}`),
    retryable: res.status === 429,
  };
}

rejectedValue is the field that makes everything downstream possible. It is captured from the payload that was sent, not from the form’s current values, because a reader can keep typing while a request is in flight — and an error attributed to a value they have already replaced is an error that should never have been shown.

Integration Guidance

Server errors join the same FieldErrorMap that local validation produces, which means everything in error state mapping patterns applies to rendering them. The difference is precedence and lifetime: a server error outranks a local one for the same field, because it was produced with information the client does not have, and it survives triggers that clear local errors.

Path translation is the other integration point, and it is where most of the practical difficulty lives. Servers describe fields in their own vocabulary — JSON Pointer, snake_case, a nested resource path — and the form describes them in the vocabulary its inputs were rendered with. One translation function, tested against captured payloads, is the whole solution; scattering replace('/', '.') calls through components is how a renamed API field becomes a silently unrendered error.

The submission lifecycle from submission state and optimistic updates supplies the states these outcomes drive. field-errors and form-error both move the submission to failed while keeping the idempotency key, so a corrected retry is still the same logical request.

Edge Cases and Failure Modes

The server names a field the form does not render. A rule about a derived or server-only field produces an error with nowhere to go. Never drop it — promote it to a form-level message so the reader at least learns why the submit failed.

The reader edits during the request. By the time the 422 arrives, the field may hold something else. Because the error records rejectedValue, the comparison is trivial: if the current value already differs, the error is stale and must not be rendered at all.

Two errors for one field. A server can legitimately return several issues for the same input. Render the first and keep the rest, exactly as error state mapping patterns prescribes — a field showing four messages at once is a field nobody reads.

Repeated groups and indices. /addresses/1/postcode refers to a position, and positions move. If the reader deletes a row between submit and response, the error now points at a different row. Key rows by a stable id and translate the index through it, or re-validate after any structural edit.

A localised message you cannot use. If the server’s wording is not in the reader’s language, or is written for an operator rather than a reader, map the code to your own copy and treat message as a fallback. This is exactly why code is required rather than optional.

The submission state each outcome leaves behind is worth writing down too, because it decides what the reader can do next:

Troubleshooting Reference

Who owns the wording

A rejection arrives with two things that could be shown to the reader: a machine-readable code and a human-readable message. Which one you render decides who owns the wording of your form, and the answer should almost always be that you do.

Server messages are written for whoever reads them first, which is usually an engineer looking at a log or a client developer reading API documentation. They leak internal vocabulary — constraint names, table names, the word validation — they are frequently untranslated, and they change without notice because nobody considers a message string a breaking change. Rendering them verbatim means your form’s copy standards apply to every string except the ones the reader sees at the moment they are most stuck.

Mapping codes to copy you own inverts that. The server’s code becomes the stable contract, your copy table becomes the wording, and an unrecognised code falls back to the server’s message so a rule shipped by the API today still surfaces something rather than nothing:

// The code is the contract; the message is the fallback. An unmapped code still
// renders — badly worded is strictly better than invisible.
const COPY: Record<string, string> = {
  email_taken:      'That address is already registered — sign in instead?',
  coupon_expired:   'That code has expired. Remove it to continue.',
  address_unserviced: 'We do not deliver to that post code yet.',
};

const messageFor = (e: ServerFieldError) => COPY[e.code] ?? e.message;

Two things follow from this that are worth doing deliberately. First, log every unmapped code, because a steady stream of one code means a rule the reader is being told about in the API’s voice rather than yours. Second, treat the code list as part of the API contract in review: a new rejection reason that ships without a code is a rejection reason your form cannot speak about properly.

Testing and QA Hooks

Capture real payloads and test the reconciler against them. A fixture directory of recorded 422, 409, 429 and 500 responses turns the whole surface into fast unit tests, and it catches the case that integration tests never reach: an API that changes its error shape without changing its status code.

it('does not render a server error the reader has already edited past', () => {
  const sent = { email: '[email protected]' };
  const out = reconcile(res422, body, sent);
  const err = (out as any).errors[0];
  expect(isStale(err, { email: '[email protected]' })).toBe(true);   // already changed
  expect(isStale(err, { email: '[email protected]' })).toBe(false);  // unchanged
});

For end-to-end coverage, assert on data-error-origin="server" rather than on message text, and add one test per row of the response table above. The 5xx row is the one worth being strict about: assert that no field carries aria-invalid after a simulated gateway failure.

Common Pitfalls

• A single error: string per field. With no origin, no code and no rejected value, none of the behaviour on this page is expressible.
• Clearing every error on change. It makes server errors disappear on a stray keypress while the problem remains.
• Rendering 5xx as validation. It blames the reader for your outage and blocks a submit that would have succeeded.
• Dropping unmapped errors. A failed submit with no visible reason is indistinguishable from a broken form.
• Trusting the message. Server wording is written for whoever wrote the API. Map codes to copy you control.

Related

• Mapping 422 Responses to Field Errors — the path translation in full
• Clearing Server Errors When a Field Changes — the lifetime rule, implemented
• Error State Mapping Patterns — the shared shape both kinds of error land in
• Submission State and Optimistic Updates — the states these outcomes drive

← Validation Logic & Schema Integration

Frequently Asked Questions