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.codeist eine stabile interne Kennung — nutze sie in deinem Error-Handling, nicht diemessage(die kann sich lokalisieren).meta.debugIdist eine ULID, die inayounelogs(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.