From 82939c0005d68906c67d6a0bbf4b4410acc93d60 Mon Sep 17 00:00:00 2001 From: Samir Boulahtit Date: Sun, 24 May 2026 00:32:42 +0200 Subject: [PATCH] docs(api): document apiClient error.status / errorCode / details surface Adds a "Frontend Error Handling (apiClient)" section to the error handling guide. Callers can branch on `error.errorCode` and read `error.details` to localise toasts instead of rendering the raw English `message`, as already done in the loyalty terminal cooldown handler. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/api/error-handling.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/docs/api/error-handling.md b/docs/api/error-handling.md index f4c8c1cd..609f61e9 100644 --- a/docs/api/error-handling.md +++ b/docs/api/error-handling.md @@ -284,6 +284,33 @@ async def invalid_token_handler(request, exc): ) ``` +## Frontend Error Handling (apiClient) + +When a request fails, the shared `apiClient` (`static/shared/js/api-client.js`) throws an `Error` with three structured properties populated from the JSON response, in addition to the `message`: + +| Property | Source | Example | +|----------|--------|---------| +| `error.status` | HTTP status code | `429` | +| `error.errorCode` | Server `error_code` field | `"POINTS_COOLDOWN"` | +| `error.details` | Server `details` object (may be `null`) | `{ cooldown_minutes: 5, cooldown_ends: "..." }` | + +This lets callers branch on a machine-readable code and localise the toast instead of rendering the raw English `message`. Pattern: + +```js +try { + await apiClient.post('/store/loyalty/transactions', payload); +} catch (error) { + if (error.errorCode === 'POINTS_COOLDOWN' || error.errorCode === 'STAMP_COOLDOWN') { + const minutes = error.details?.cooldown_minutes ?? ''; + Utils.showToast(I18n.t('loyalty.store.terminal.cooldown_wait_minutes', { minutes }), 'warning'); + } else { + Utils.showToast(I18n.t('loyalty.store.terminal.transaction_failed', { message: error.message }), 'error'); + } +} +``` + +Generic FastAPI errors that don't carry `error_code` / `details` will leave those properties `undefined` / `null`, so a `?.` chain is the right guard. + ## Related Documentation - [Authentication](authentication.md) - Authentication-related exceptions