Errors, empty results and retries
Distinguish unavailable services, empty content and denied access, while preserving user input.
Public read failures
Article details return null only for 404 and list failures throw. SiteSDK validates the response envelope and public shape rather than accepting errors as settings. I18n failures should show built-in application copy with retry.
import type { Shell } from '@mosaic-base/shell';
import type { ArticleSDK, SiteSDK, I18nSDK } from '@mosaic-base/client-sdk';
import type { AuthClient, ServerAuthClient } from '@mosaic-base/auth-sdk';
// Declare once in your application's type contract, never import SDK implementations.
declare module '@mosaic-base/shell/contracts' {
interface SdkRegistry {
'site.config': Pick<SiteSDK, 'getConfig'>;
'content.articles': Pick<ArticleSDK, 'list' | 'getBySlug' | 'getPreview' | 'search'>;
'i18n.messages': Pick<I18nSDK, 'load' | 't' | 'clearCache' | 'refresh'>;
'auth.client': AuthClient | ServerAuthClient;
}
}
export async function loadWithFeedback(shell: Shell) {
try {
const articles = await shell.getSdk('content.articles');
const result = await articles.list({ language: 'en-US' });
return { state: result.items.length ? 'ready' : 'empty', articles: result.items };
} catch { return { state: 'unavailable', message: 'Reload to try again.' }; }
}Identity and permission errors
401 requires sign-in verification or recovery. 403 indicates a resource policy or permission denial; do not fix it by weakening guards. AuthSDK returns data/error, so check error before using data.
Write retries and diagnostics
Preserve failed form input, report the state and unlock submission. When write completion is uncertain, reread state before retrying; automatic retries require idempotency. Record stage, HTTP/business code and requestId, never tokens, Cookies or secrets.