Fehlerreferenz

Überblick

Alle Fehler der API mit Status, Bedeutung und Beispielantwort. Jede Fehlerantwort hat dasselbe Format (Content-Type: application/problem+json):

Feld	Inhalt
type	https://problems.caryo/<errorCode>
title	Beschreibung in Klartext (kann sich ändern – nicht maschinell auswerten)
status	HTTP-Status
instance	aufgerufener Pfad
extensions.errorCode	fester Code – darauf reagiert Ihr System
extensions.traceId	Kennung für Rückfragen beim Support
extensions.…	je nach Fehler weitere Angaben (siehe unten)

Werten Sie immer extensions.errorCode aus, nicht title.

Anmeldung & Rechte

invalid_token – 401

Kein Token, falscher Token, widerrufener Token, deaktivierter Benutzer oder Rolle ohne API-Berechtigung.

{
  "type": "https://problems.caryo/invalid_token",
  "title": "Kein gültiges API-Token.",
  "status": 401,
  "instance": "/api/external/v1/orders",
  "extensions": { "errorCode": "invalid_token", "traceId": "00-4bf92f…-01" }
}

token_expired – 401

Der Token ist abgelaufen. Erstellen Sie im Cockpit einen neuen.

{
  "type": "https://problems.caryo/token_expired",
  "title": "Das Token ist abgelaufen.",
  "status": 401,
  "extensions": { "errorCode": "token_expired", "traceId": "…" }
}

api_access_not_in_plan – 403

Die API ist im Paket Ihrer Firma nicht enthalten.

{
  "type": "https://problems.caryo/api_access_not_in_plan",
  "title": "Die API ist im aktuellen Paket nicht enthalten.",
  "status": 403,
  "extensions": { "errorCode": "api_access_not_in_plan", "traceId": "…" }
}

insufficient_scope – 403

Dem Token fehlt das Recht „Lesen“ bzw. „Schreiben“ für diesen Aufruf.

{
  "type": "https://problems.caryo/insufficient_scope",
  "title": "Dem Token fehlt das nötige Recht (read bzw. write).",
  "status": 403,
  "extensions": { "errorCode": "insufficient_scope", "traceId": "…" }
}

forbidden_for_role – 403

Ihre Rolle darf diese Aktion nicht, z. B. stornieren oder Fahrer zuweisen als Auftraggeber.

{
  "type": "https://problems.caryo/forbidden_for_role",
  "title": "Die Rolle des Token-Besitzers erlaubt diese Aktion nicht.",
  "status": 403,
  "extensions": { "errorCode": "forbidden_for_role", "traceId": "…" }
}

rate_limited – 429

Zu viele Anfragen. Der Header Retry-After nennt die Wartezeit in Sekunden.

HTTP/1.1 429 Too Many Requests
Retry-After: 42
Content-Type: application/problem+json

{
  "type": "https://problems.caryo/rate_limited",
  "title": "Zu viele Anfragen. Bitte 42 Sekunden warten.",
  "status": 429,
  "extensions": { "errorCode": "rate_limited", "traceId": "…" }
}

Eingaben

validation_failed – 400 / 422

Die Anfrage ist unvollständig oder hat ein falsches Format.

• 400: kein gültiges JSON oder ein Feld mit falschem Typ (z. B. Text statt Adress-Objekt). Details stehen in extensions.errors.
• 422: Pflichtangabe fehlt (z. B. pickup), ein Text ist zu lang oder ein Zeitpunkt hat keine Zeitzone bzw. ist ungültig. Welche Felder betroffen sind, steht im title.

{
  "type": "https://problems.caryo/validation_failed",
  "title": "Die Anfrage ist kein gültiges JSON oder enthält Felder im falschen Format.",
  "status": 400,
  "extensions": {
    "errorCode": "validation_failed",
    "traceId": "…",
    "errors": { "pickup": ["Error converting value \"Leipzig\" …"] }
  }
}

{
  "type": "https://problems.caryo/validation_failed",
  "title": "pickup ist Pflicht.",
  "status": 422,
  "extensions": { "errorCode": "validation_failed", "traceId": "…" }
}

{
  "type": "https://problems.caryo/validation_failed",
  "title": "Zeitpunkt ohne Zeitzone oder ungültig: pickupAt, deliveryAt. Erwartet ISO 8601 mit Zeitzone, z. B. 2026-11-03T08:00:00+01:00.",
  "status": 422,
  "extensions": { "errorCode": "validation_failed", "traceId": "…" }
}

Aufträge

order_not_found – 404

Den Auftrag gibt es nicht, oder er ist für Ihren Token nicht sichtbar (z. B. Auftrag einer anderen Person bei der Rolle Auftraggeber).

{
  "type": "https://problems.caryo/order_not_found",
  "title": "Den Auftrag gibt es nicht oder er ist für dieses Token nicht sichtbar.",
  "status": 404,
  "extensions": { "errorCode": "order_not_found", "traceId": "…" }
}

duplicate_external_id – 409

Mit dieser externalId haben Sie schon einen Auftrag angelegt. Der vorhandene Auftrag steht vollständig in extensions.order – Sie können ihn direkt weiterverwenden.

{
  "type": "https://problems.caryo/duplicate_external_id",
  "title": "Ein Auftrag mit der externen Nummer 'LOG-2026-00123' existiert bereits (LG12345).",
  "status": 409,
  "extensions": {
    "errorCode": "duplicate_external_id",
    "traceId": "…",
    "order": { "id": 4711, "orderNumber": "LG12345", "externalId": "LOG-2026-00123", "status": "open" }
  }
}

billing_blocked – 403

Neue Fahrten sind gesperrt, weil die Abrechnung nicht eingerichtet oder eine Plattformrechnung offen ist. Bitte im Cockpit unter Einstellungen → Konto klären.

{
  "type": "https://problems.caryo/billing_blocked",
  "title": "New trips cannot be created until the platform invoice is paid.",
  "status": 403,
  "extensions": { "errorCode": "billing_blocked", "traceId": "…" }
}

multi_leg_not_supported – 422

Der Auftrag ist in Teilstrecken aufgeteilt. Fahrer bitte im Cockpit planen.

{
  "type": "https://problems.caryo/multi_leg_not_supported",
  "title": "Der Auftrag ist in Teilstrecken aufgeteilt; Fahrer bitte im Cockpit planen.",
  "status": 422,
  "extensions": { "errorCode": "multi_leg_not_supported", "traceId": "…" }
}

driver_not_found – 422

Kein aktiver Fahrer Ihrer Firma mit dieser E-Mail. Gültige E-Mails liefert GET /drivers.

{
  "type": "https://problems.caryo/driver_not_found",
  "title": "Kein aktiver Fahrer mit der E-Mail 'max@spedition.de'.",
  "status": 422,
  "extensions": { "errorCode": "driver_not_found", "traceId": "…" }
}

Adressen & Kunden

address_not_found – 422

Die angegebene Adress-id ist nicht sichtbar, oder es gibt keine gespeicherte Adresse mit diesem Namen und für eine neue fehlen name oder city. extensions.field nennt pickup oder delivery.

{
  "type": "https://problems.caryo/address_not_found",
  "title": "pickup: Keine gespeicherte Adresse gefunden; für eine neue sind mindestens name und city nötig.",
  "status": 422,
  "extensions": { "errorCode": "address_not_found", "traceId": "…", "field": "pickup" }
}

address_ambiguous – 422

Mehrere gespeicherte Adressen passen. Wählen Sie eine aus extensions.candidates und schicken Sie deren id mit – oder ergänzen Sie city bzw. zipCode.

{
  "type": "https://problems.caryo/address_ambiguous",
  "title": "pickup: Mehrere gespeicherte Adressen passen; bitte id, Ort oder PLZ angeben.",
  "status": 422,
  "extensions": {
    "errorCode": "address_ambiguous",
    "traceId": "…",
    "field": "pickup",
    "candidates": [
      { "id": 9001, "name": "Autohaus Müller", "street": "Hauptstraße", "number": "12", "zipCode": "04109", "city": "Leipzig" },
      { "id": 9017, "name": "Autohaus Müller", "street": "Ringweg", "number": "3", "zipCode": "04109", "city": "Leipzig" }
    ]
  }
}

client_not_found – 422

Kein Kunde mit dieser id bzw. diesem Namen. Kunden werden über die API nicht angelegt – bitte im Cockpit anlegen.

{
  "type": "https://problems.caryo/client_not_found",
  "title": "Kunde nicht gefunden.",
  "status": 422,
  "extensions": { "errorCode": "client_not_found", "traceId": "…" }
}

client_ambiguous – 422

Mehrere Kunden mit diesem Namen. Schicken Sie client.id aus extensions.candidates mit.

{
  "type": "https://problems.caryo/client_ambiguous",
  "title": "Mehrere Kunden passen; bitte die id angeben.",
  "status": 422,
  "extensions": {
    "errorCode": "client_ambiguous",
    "traceId": "…",
    "candidates": [
      { "id": 17, "name": "Logether GmbH", "city": "Leipzig" },
      { "id": 23, "name": "Logether GmbH", "city": "Dresden" }
    ]
  }
}

Sonstige Fehler

• 500 / 503: unerwarteter Fehler auf unserer Seite. Nach kurzer Wartezeit mit derselben externalId erneut senden – so entsteht kein Doppel. Bleibt der Fehler, bitte mit traceId an den Support.

Siehe auch

• Fehler & Limits
• Aufträge per API
• Adressen & Kunden erkennen