Error Codes

Wenn ein API-Call fehlschlägt, antwortet aYOUne mit einem strukturierten Fehler-Envelope. Dieser Guide erklärt die wichtigsten HTTP-Codes und zeigt, wie du den Fehler programmatisch auswertest.

Fehler-Envelope

Auch im Fehlerfall hält die Plattform am Standard-Format fest:

{
  "payload": {
    "error": {
      "code": "VALIDATION_FAILED",
      "message": "Field 'email' is required",
      "field": "email",
      "debugId": "01J7XYZ..."
    }
  },
  "meta": { "version": "2026.50.0", "debugId": "01J7XYZ..." }
}

Wichtig:

payload.error.code ist eine stabile interne Kennung — nutze sie in deinem Error-Handling, nicht die message (die kann sich lokalisieren).
meta.debugId ist eine ULID, die in ayounelogs (Winston-Log-Collection mit ~1h TTL) auffindbar ist. Bei Tickets an Tolinax-Support immer mitschicken.

Statuscodes

HTTP	code	Bedeutung
400	`BAD_REQUEST`	Generisch — fehlerhafte Query
400	`VALIDATION_FAILED`	Ein oder mehrere Felder ungültig (`payload.error.fields[]`)
401	`UNAUTHORIZED`	Token fehlt/ungültig/abgelaufen
401	`TOKEN_EXPIRED`	Access-Token abgelaufen — refreshe
403	`FORBIDDEN`	Token gültig, aber Right fehlt
403	`LICENSE_BLOCKED`	Modul nicht im Customer-Paket
404	`NOT_FOUND`	Datensatz oder Route existiert nicht
409	`CONFLICT`	Eindeutigkeit verletzt (z.B. doppelter Slug)
410	`GONE`	Endpoint deprecated und entfernt
422	`UNPROCESSABLE`	Schema-OK, Business-Rule verletzt
429	`RATE_LIMITED`	Tokens-Bucket leer; siehe `Retry-After`
500	`INTERNAL_ERROR`	Plattform-Bug — wird als Task (Type=Bug) persistiert
502/503	`UPSTREAM_DOWN`	Modul-API nicht erreichbar

Retry-Strategie

Nicht jeder Fehler ist es wert, retried zu werden:

Code	Retry?	Strategie
4xx (außer 429)	nein	Code anpassen
401	ja	erst refresh, dann retry
429	ja	`Retry-After`-Header beachten
5xx	ja	exponential backoff, max 3 Versuche

Das offizielle TypeScript-SDK implementiert diese Logik bereits.

Beispiel: Robustes Error-Handling

try {
  const consumer = await client.crm.consumers.create({ email: "" });
} catch (err) {
  if (err.response?.status === 400 && err.response?.data?.payload?.error?.code === "VALIDATION_FAILED") {
    const fields = err.response.data.payload.error.fields;
    console.error("Bitte fehlerhafte Felder korrigieren:", fields);
  } else if (err.response?.status === 401) {
    await client.auth.refresh();
    // retry
  } else {
    console.error("Unerwarteter Fehler — debugId:", err.response?.data?.meta?.debugId);
  }
}

Errors als Tasks

Plattform-interne 5xx-Fehler werden zusätzlich als tasks-Records mit type: "Bug" persistiert (Plattform-Konvention) — sie tauchen also auch im CRM-Modul auf, sind aber Read-Side-gefiltert. Mehr im Admin-Handbook.