Foutafhandeling

Name: OptimoCMS SDK
Author: OptimoCMS

De SDK gooit getypeerde errors die je kunt catchen en afhandelen.

OptimoCMSError

Alle API errors worden gewrapt in een OptimoCMSError:

import { OptimoCMS, OptimoCMSError } from '@optimocms/sdk';

const cms = new OptimoCMS({ apiKey: process.env.OPTIMOCMS_API_KEY! });

try {
  const page = await cms.pages.get('site_abc123', 'ongeldig-id');
} catch (error) {
  if (error instanceof OptimoCMSError) {
    console.error('Status:', error.status);       // 404
    console.error('Code:', error.code);            // "NOT_FOUND"
    console.error('Message:', error.message);      // "Page not found"
    console.error('Request ID:', error.requestId); // "req_abc123"
  }
}

Error properties

Property	Type	Beschrijving
`status`	`number`	HTTP status code (400, 401, 403, 404, 409, 429, 500)
`code`	`string`	Machine-readable error code
`message`	`string`	Menselijk leesbaar foutbericht
`requestId`	`string`	Uniek request ID voor debugging
`details`	`object \| undefined`	Extra details (bijv. validatiefouten)

Error codes

Status	Code	Wanneer
`400`	`BAD_REQUEST`	Ongeldige request body of parameters
`400`	`VALIDATION_ERROR`	Velden voldoen niet aan validatieregels
`401`	`UNAUTHORIZED`	Geen of ongeldige API key
`403`	`FORBIDDEN`	Key mist de benodigde scope
`404`	`NOT_FOUND`	Resource bestaat niet
`409`	`CONFLICT`	Slug conflict of duplicate resource
`429`	`RATE_LIMIT_EXCEEDED`	Te veel requests
`500`	`INTERNAL_ERROR`	Server-side fout

Specifieke error handling

Validatiefouten

try {
  await cms.pages.create('site_abc123', {
    title: '',  // te kort
    slug: 'a b c',  // ongeldige karakters
  });
} catch (error) {
  if (error instanceof OptimoCMSError && error.code === 'VALIDATION_ERROR') {
    console.error('Validatiefouten:', error.details);
    // { fields: { title: "must be at least 1 character", slug: "invalid characters" } }
  }
}

404 Not Found

try {
  const page = await cms.pages.get('site_abc123', 'page_niet_bestaand');
} catch (error) {
  if (error instanceof OptimoCMSError && error.status === 404) {
    console.log('Pagina niet gevonden, maak een nieuwe aan');
    await cms.pages.create('site_abc123', {
      title: 'Nieuwe Pagina',
      slug: 'nieuwe-pagina',
    });
  }
}

409 Conflict

try {
  await cms.pages.create('site_abc123', {
    title: 'Over Ons',
    slug: 'over-ons',  // slug bestaat al
  });
} catch (error) {
  if (error instanceof OptimoCMSError && error.status === 409) {
    console.log('Slug bestaat al, gebruik een andere');
  }
}

Automatische retry

De SDK retried automatisch bij 429 (rate limit) en 5xx (server errors) met exponential backoff.

Standaard gedrag

Poging	Wachttijd
1e retry	1 seconde
2e retry	2 seconden
3e retry	4 seconden

Na maxRetries pogingen gooit de SDK de error alsnog.

Retry configureren

const cms = new OptimoCMS({
  apiKey: process.env.OPTIMOCMS_API_KEY!,

  // Meer retries voor batch operaties
  maxRetries: 5,
});

Retry uitschakelen

const cms = new OptimoCMS({
  apiKey: process.env.OPTIMOCMS_API_KEY!,
  maxRetries: 0,  // geen retry
});

Welke errors worden geretried?

Status	Retry?	Reden
`429`	Ja	Rate limit — wacht op `Retry-After` header
`500`	Ja	Server error — tijdelijk probleem
`502`	Ja	Bad gateway
`503`	Ja	Service unavailable
`504`	Ja	Gateway timeout
`400`	Nee	Client error — retry helpt niet
`401`	Nee	Auth error — fix je API key
`403`	Nee	Scope error — voeg scopes toe
`404`	Nee	Resource bestaat niet
`409`	Nee	Conflict — verander de data

Rate limit handling

Bij een 429 response leest de SDK de Retry-After header en wacht precies zo lang:

// De SDK doet dit automatisch:
// 1. Request → 429 (Retry-After: 45)
// 2. Wacht 45 seconden
// 3. Retry request
// 4. 200 OK ✓

Als je handmatig rate limits wilt afhandelen:

const cms = new OptimoCMS({
  apiKey: process.env.OPTIMOCMS_API_KEY!,
  maxRetries: 0,  // handmatige controle
});

try {
  await cms.sites.list();
} catch (error) {
  if (error instanceof OptimoCMSError && error.status === 429) {
    const retryAfter = error.details?.retryAfter ?? 60;
    console.log(`Rate limited. Wacht ${retryAfter} seconden...`);
    await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
    await cms.sites.list();  // opnieuw proberen
  }
}

Netwerk errors

Bij timeout of netwerk errors gooit de SDK een standaard Error (geen OptimoCMSError):

try {
  await cms.sites.list();
} catch (error) {
  if (error instanceof OptimoCMSError) {
    // API error (4xx/5xx)
  } else if (error instanceof Error) {
    // Netwerk/timeout error
    console.error('Netwerk fout:', error.message);
  }
}

Compleet voorbeeld

import { OptimoCMS, OptimoCMSError } from '@optimocms/sdk';

const cms = new OptimoCMS({
  apiKey: process.env.OPTIMOCMS_API_KEY!,
  maxRetries: 3,
  timeout: 15_000,
});

async function updatePageSafely(siteId: string, pageId: string, title: string) {
  try {
    const result = await cms.pages.update(siteId, pageId, { title });
    console.log(`Pagina bijgewerkt: ${result.data.title}`);
    return result.data;
  } catch (error) {
    if (!(error instanceof OptimoCMSError)) {
      console.error('Netwerk fout:', error);
      throw error;
    }

    switch (error.status) {
      case 401:
        throw new Error('API key is ongeldig. Check je configuratie.');
      case 403:
        throw new Error(`Scope ontbreekt: ${error.message}`);
      case 404:
        console.log('Pagina niet gevonden, wordt overgeslagen');
        return null;
      case 429:
        throw new Error('Rate limit bereikt na alle retries');
      default:
        throw error;
    }
  }
}

Try it — curl equivalent:

# Error responses hebben dezelfde JSON structuur
curl -i https://api.optimocms.com/v1/sites/site_abc123/pages/ongeldig-id \
  -H "X-Api-Key: jouw_api_key"

# HTTP/1.1 404 Not Found
# {"error":{"code":"NOT_FOUND","message":"Page not found"},"meta":{"requestId":"req_abc123",...}}

Try it — MCP:

Haal pagina "ongeldig-id" op van site site_abc123.
→ De MCP server retourneert een duidelijke foutmelding.

Volgende stappen

Paginering — Grote datasets ophalen
Authenticatie — Scopes en rate limits
API Referentie — Alle endpoints

Foutafhandeling

On this page