Konventionen
IDs, Zeitstempel, Fehlerstruktur, Versionierung und Wiederholungen.
| Konvention | Regel |
|---|---|
| IDs | UUIDs, undurchsichtig. Speichern Sie sie vollständig; niemals einen davon parsen oder kürzen |
| Zeitstempel | RFC 3339 in UTC, z. B. 2026-09-22T04:10:00Z |
| Unbekannte Felder | ignorieren Sie sie. Neue Antwortfelder und neue Statuswerte können ohne Versionsänderung hinzukommen |
| Versionierung | das Präfix trägt die Hauptversion. Eine inkompatible Änderung erhält ein neues Präfix und Vorankündigung |
| Fehler | {"description": "…", "error": {"error_code": "…", "error_attributes": {…}}} — verzweigen Sie nach error.error_code, protokollieren Beschreibung, nie anhand seines Textes abgleichen. Siehe Fehler & Limits |
| Wiederholungen | beachten Retry-After bei 429. Bei 5xx mit exponentiellem Backoff und Jitter erneut versuchen |
Idempotenz
Senden Sie einen idempotency_key bei jedem Lauf, den Sie starten. Es ist Ihr eigener String — eine Episodennummer, eine Job-ID, alles, was für diese Arbeitseinheit stabil ist.
- Derselbe Schlüssel mit dem selben Inhalt gibt den bereits vorhandenen Lauf zurück, anstatt einen zweiten zu starten.
- Derselbe Schlüssel mit einem anderen Inhalt wird abgelehnt mit
idempotency_conflict. Verwenden Sie für neue Arbeit einen neuen Schlüssel.
Dadurch ist ein erneuter Versuch nach einem Timeout sicher, und genau das ist der Unterschied zwischen einem Lauf und einem Duplikat, für das Ihnen Gebühren berechnet werden.
Nachverfolgung
Jede Antwort enthält x-morphic-trace-id. Protokollieren Sie sie. Wenn Sie ein Problem melden, ist diese ID das, was uns ermöglicht, den Lauf in Sekunden zu finden, statt Sie nach einem Zeitfenster zu fragen.