Fehler & Limits

Fehlerformat

Fehler kommen als application/problem+json. Maßgeblich ist extensions.errorCode; title erklärt den Fehler in Klartext.

{
  "type": "https://problems.caryo/client_not_found",
  "title": "Kunde nicht gefunden.",
  "status": 422,
  "instance": "/api/external/v1/orders",
  "extensions": { "errorCode": "client_not_found", "traceId": "00-4bf9…-01" }
}

Bei Rückfragen an den Support bitte die traceId mitschicken.

Fehlercodes

Status	errorCode	Bedeutung	Was tun?
401	invalid_token	Token fehlt, ist falsch, widerrufen oder der Benutzer ist deaktiviert	Token prüfen bzw. neu erstellen
401	token_expired	Token abgelaufen	Neuen Token erstellen
403	api_access_not_in_plan	Die API ist im Paket nicht enthalten	Vertrieb kontaktieren
403	insufficient_scope	Token hat das Recht Lesen bzw. Schreiben nicht	Token mit passendem Recht erstellen
403	forbidden_for_role	Ihre Rolle darf das nicht (z. B. stornieren als Auftraggeber)	Im Cockpit bzw. mit passender Rolle erledigen
403	billing_blocked	Neue Fahrten sind gesperrt (Abrechnung offen)	Abrechnung im Cockpit klären
404	order_not_found	Auftrag gibt es nicht oder ist für Sie nicht sichtbar	id prüfen
409	duplicate_external_id	Auftrag mit dieser externalId existiert schon	Vorhandenen Auftrag aus extensions.order verwenden
422	validation_failed	Pflichtangabe fehlt oder ungültig, Text zu lang, Zeitpunkt ohne Zeitzone	Anfrage korrigieren
422	address_not_found	Gespeicherte Adresse nicht gefunden bzw. für neue fehlen name/city	Felder ergänzen oder id prüfen
422	address_ambiguous	Mehrere gespeicherte Adressen passen	id aus extensions.candidates mitschicken
422	client_not_found	Kunde nicht gefunden	Kunden im Cockpit anlegen oder Namen prüfen
422	client_ambiguous	Mehrere Kunden passen	client.id mitschicken
422	driver_not_found	Kein aktiver Fahrer mit dieser E-Mail	E-Mail aus GET /drivers verwenden
422	multi_leg_not_supported	Auftrag hat Teilstrecken	Fahrer im Cockpit planen
429	rate_limited	Zu viele Anfragen	Wartezeit aus Retry-After abwarten

Rate-Limits

Anfragen pro Minute und Firma (alle Tokens zusammen):

Paket	Anfragen pro Minute
Enterprise	300
Business (freigeschaltet)	60
Basic (freigeschaltet)	30

Wird das Limit überschritten, antwortet die API mit 429 und dem Header Retry-After (Sekunden).

Empfehlungen für Ihr System

• 🔁 Bei 429 und bei Netzwerkfehlern: nach Retry-After bzw. einigen Sekunden erneut versuchen – mit derselben externalId, dann entstehen keine Doppel.
• ⛔ Bei 4xx außer 429 nicht automatisch wiederholen, sondern die Anfrage korrigieren.
• 🪵 traceId mitloggen.

Siehe auch

• Fehlerreferenz mit Beispielantworten
• Aufträge per API
• Zugang & Token