Recept

Validációs hibák kezelése

Az API 422 státusszal, strukturált hibalistával válaszol — így parsold és jelenítsd meg felhasználó-barátul.

Haladó~20 perc4 lépés

Előfeltételek

Ismered a QUiCK API kérés/válasz alapokat
Van egy űrlap vagy import, ahol felhasználói adatot küldesz be

1. A 422 válasz alakja

Minden validációs hibát ugyanabban a formátumban ad vissza az API:

json

{
  "error": {
    "code": "validation_failed",
    "message": "A kérés több mező hibáját tartalmazza.",
    "details": [
      { "field": "customer.tax_number", "code": "invalid_format", "message": "Az adószám nem érvényes." },
      { "field": "lines[0].quantity", "code": "must_be_positive", "message": "A mennyiség pozitív legyen." }
    ]
  }
}

2. Fetch wrapper hibalogikával

export class QuickValidationError extends Error {
  constructor(public details: { field: string; code: string; message: string }[]) {
    super("validation_failed");
  }
}

export async function quickCall<T>(path: string, init?: RequestInit): Promise<T> {
  const res = await quickFetch(path, init);
  if (res.status === 422) {
    throw new QuickValidationError(res.error.details);
  }
  return res as T;
}

3. Hibák leképzése űrlapmezőkre

A field érték pont-notációjú path — a legtöbb form library (react-hook-form, Formik) közvetlenül fel tudja használni.

try {
  await createInvoice(values);
} catch (err) {
  if (err instanceof QuickValidationError) {
    for (const d of err.details) {
      form.setError(d.field as never, { message: d.message });
    }
    return;
  }
  throw err;
}

4. Nem-mező hibák (form-level)

Ha a field értéke _root vagy hiányzik, ez az egész beküldést érintő hiba (pl. üzleti szabály). Mutasd meg a form tetején, ne mezőnél.

A `code` értékek stabilak; ezekre feliratkozhatsz és lokalizálhatod őket. A `message` a szerver-oldali magyar szöveg.

Kapcsolódó endpointok

POST/v1/invoices
PATCH/v1/invoices/{id}

Kapcsolódó fogalmak

validation_failed tax_number

Gyakori hibák

Csak a message mezőt mutatod

A felhasználó nem tudja majd, melyik mezőt kell javítania. Mindig kösd a hibát a field-hez.

A code-ot fordítod le a fronton

A szerver már lokalizált message-t ad vissza. A code inkább analitikára és programozott elágazásra való.