Exit-Codes der CLI und was du jeweils tust

Exit-Codes sind Teil des Vertrags der CLI mit Agenten und CI. Verzweige auf sie, statt Fehlertexte abzugleichen.

0 Erfolg. Der Befehl hat getan, was er sagt.
1 allgemeiner Fehler: falsche Nutzung, ein Netzwerkfehler oder ein Auftrag, der auf dem Server gescheitert ist. Etwas ist wirklich kaputt.
2 nicht angemeldet. Kein Key, oder der Key wurde abgelehnt. Repariere die Zugangsdaten und versuch es dann erneut.
3 verboten. Der Key ist gültig, hat aber nicht den nötigen Scope. Den Key zu erweitern ist eine Entscheidung für einen Menschen, kein erneuter Versuch.
4 Rate-Limit oder Tageskontingent erreicht. Warte und mach später weiter.
5 Upgrade oder Zahlung nötig. Die Meldung enthält die URL für das Upgrade.

Code 5 ist bewusst von 1 getrennt. Ein Agent kann so "dieses Konto braucht einen bezahlten Plan" von "etwas ist kaputt" unterscheiden und reagieren, indem er dem Menschen einen Link zeigt, statt es in einer Schleife erneut zu versuchen.

Ein Shell-Muster, das funktioniert

npx argorant export --keywords fintech --country Germany -n 500 -o leads.csv --yes
case $? in
  0) echo "done" ;;
  2|3) echo "credential problem, stopping"; exit 1 ;;
  4) echo "rate limited, retry later" ;;
  5) echo "needs credits, notify the human" ;;
  *) echo "failed" ;;
esac

Terminal, in dem ein Skript einen Exit-Code ungleich null behandelt

Die Codes entsprechen direkt den HTTP-Statuscodes der REST-API: Aus 401 wird 2, aus 403 3, aus 429 4 und aus 402 5. Agenten, die beide Schnittstellen nutzen, können einen gemeinsamen Weg zur Fehlerbehandlung haben.