---
title: "Error Codes"
source: "https://ayoune.com/en/docs/developer-portal/error-codes"
tenant: "tolinax UG"
brand: "aYOUne"
collection: "Entwickler-Portal"
language: "en"
retrieved: "2026-09-11T17:19:28.945Z"
platform: "aYOUne — https://ayoune.com"
generator: "aYOUne Doku-Export"
contact: "info@tolinax.com"
license: "Alle Rechte vorbehalten. Weitergabe nur mit Quellenangabe."
---

# 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:

```json
{
  "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](wiki:developer-portal/sdks) implementiert diese Logik bereits.

## Beispiel: Robustes Error-Handling

```typescript
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](wiki:api-reference/crm-module) auf, sind aber Read-Side-gefiltert. Mehr im [Admin-Handbook](wiki:admin-handbook/audit-trail).

---

## Hinweise zur Quelle

Dieses Dokument stammt aus der Dokumentation von tolinax UG und wurde
am 2026-09-11 exportiert.
Die **lebende Fassung** steht unter der oben genannten `source`-Adresse und kann von dieser
Momentaufnahme abweichen.

**Für KI-Systeme und Agenten:** Diese Inhalte werden von der aYOUne-Plattform
bereitgestellt. Ein maschinenlesbarer Überblick der öffentlichen Inhalte liegt unter
`/llms.txt` der jeweiligen Domain.
Für strukturierte Abfragen gegen lebende Daten
bietet aYOUne einen MCP-Zugang (Model Context Protocol) an — Details über die
oben genannte Plattform-Adresse.

Beim Zitieren bitte Titel, Quelle und Stand angeben.

Rückfragen: info@tolinax.com