Fehler

Die Form

Jeder Fehlschlag liefert application/problem+json nach RFC 9457. Der HTTP-Status nennt die Klasse des Problems; code nennt genau welches.

HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json
X-Request-Id: req_4b81f0c9

{
  "type": "https://skautik.com/docs/developers/errors#validation_failed",
  "title": "Validation failed",
  "status": 422,
  "code": "validation_failed",
  "detail": "One or more fields could not be accepted.",
  "request_id": "req_4b81f0c9",
  "errors": [
    {
      "field": "price",
      "code": "out_of_range",
      "detail": "Must be a positive integer in minor units."
    },
    {
      "field": "address.country",
      "code": "unknown_value",
      "detail": "Expected an ISO 3166-1 alpha-2 code."
    }
  ]
}

Das Feld errors erscheint nur bei 422. Es benennt alle Probleme auf einmal statt nur das erste, ein Formular lässt sich also in einem Durchgang korrigieren statt Feld für Feld über mehrere Runden.

Verzweigen Sie über code und nicht über die Prosa in title oder detail. Der Code ist stabil; die Prosa ist für Menschen geschrieben und kann umformuliert werden.

Codes

Code	Status	Bedeutung	Was zu tun ist
`authentication_required`	401	Kein Schlüssel, oder ein ungültiger.	Header oder Schlüssel korrigieren. Unverändert erneut zu senden wird nie gelingen.
`permission_denied`	403	Gültiger Schlüssel, aber Berechtigung oder Eigentümerschaft am Datensatz verbieten das.	Einen Schlüssel mit Schreibberechtigung nutzen, oder aufhören, einen Datensatz ändern zu wollen, den Sie nicht veröffentlicht haben.
`not_found`	404	Keine solche Ressource, oder keine, die Ihr Schlüssel sehen darf.	Als Abwesenheit behandeln. Kein vorübergehender Fehler.
`conflict`	409	Ein Idempotency-Key wurde mit anderem Rumpf wiederverwendet.	Für eine wirklich neue Anlage einen frischen Schlüssel erzeugen.
`managed_by_import`	409	Der Datensatz gehört einer Importquelle, die dafür maßgeblich ist.	Im System ändern, das den Import speist, nicht hier.
`precondition_failed`	412	If-Match passte nicht zum aktuellen ETag.	Erneut lesen, Änderung erneut anwenden, einmal erneut versuchen.
`payload_too_large`	413	Der Upload überschreitet das Limit dieses Endpunkts.	Vor dem Upload verkleinern. Dieselben Bytes nicht erneut senden.
`unsupported_media_type`	415	Content-Type fehlt oder wird nicht angenommen.	application/json senden, oder multipart/form-data für Uploads.
`validation_failed`	422	Der Rumpf ließ sich lesen, aber ein Feld ist nicht annehmbar.	Das Feld errors lesen; jeder Eintrag nennt ein Feld und den Grund.
`rate_limited`	429	Spitzenlimit überschritten. Das Monatsvolumen weist nicht ab.	Retry-After abwarten, dann mit Streuung erneut versuchen.
`internal_error`	500	Ein Fehler auf unserer Seite.	Mit exponentiell wachsender Wartezeit erneut versuchen. Bei Fortbestehen die request_id nennen.
`service_unavailable`	503	Vorübergehend nicht bedienbar, meist während einer Auslieferung.	Mit wachsender Wartezeit erneut versuchen. Löst sich meist in Sekunden.

Was einen erneuten Versuch wert ist

Die Regel ist einfach, und sie falsch anzuwenden ist die häufigste Art, wie eine Anbindung aus einem kleinen Ausfall einen großen macht.

4xx: nicht erneut versuchen, außer bei 429. Die Anfrage ist falsch, und sie zu wiederholen bleibt falsch. Die Ausnahmen sind 429 und 412, das man nach erneutem Lesen einmal wiederholt.
5xx: erneut versuchen, mit exponentiell wachsender Wartezeit und Streuung, bis zu einem begrenzten Budget. Nie in einer engen Schleife: Ein Dienst, der kämpft, erholt sich langsamer, je stärker man ihn drückt.
Timeouts sind mehrdeutig. Eine Anfrage, die in ein Timeout lief, kann trotzdem ausgeführt worden sein. Genau dafür sind Idempotenzschlüssel bei Schreibvorgängen da.

Ein Problem melden

Nennen Sie die request_id, wenn Sie an support@skautik.com schreiben. Damit finden wir genau diese Anfrage; ohne sie fragen wir zuerst nach einer Reproduktion. Protokollieren Sie den Header bei jedem fehlgeschlagenen Aufruf, damit er da ist, wenn Sie ihn brauchen.

Die Form

Jeder Fehlschlag liefert application/problem+json nach RFC 9457. Der HTTP-Status nennt die Klasse des Problems; code nennt genau welches.

HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json
X-Request-Id: req_4b81f0c9

{
  "type": "https://skautik.com/docs/developers/errors#validation_failed",
  "title": "Validation failed",
  "status": 422,
  "code": "validation_failed",
  "detail": "One or more fields could not be accepted.",
  "request_id": "req_4b81f0c9",
  "errors": [
    {
      "field": "price",
      "code": "out_of_range",
      "detail": "Must be a positive integer in minor units."
    },
    {
      "field": "address.country",
      "code": "unknown_value",
      "detail": "Expected an ISO 3166-1 alpha-2 code."
    }
  ]
}

Verzweigen Sie über code und nicht über die Prosa in title oder detail. Der Code ist stabil; die Prosa ist für Menschen geschrieben und kann umformuliert werden.

Codes

Code	Status	Bedeutung	Was zu tun ist
`authentication_required`	401	Kein Schlüssel, oder ein ungültiger.	Header oder Schlüssel korrigieren. Unverändert erneut zu senden wird nie gelingen.
`permission_denied`	403	Gültiger Schlüssel, aber Berechtigung oder Eigentümerschaft am Datensatz verbieten das.	Einen Schlüssel mit Schreibberechtigung nutzen, oder aufhören, einen Datensatz ändern zu wollen, den Sie nicht veröffentlicht haben.
`not_found`	404	Keine solche Ressource, oder keine, die Ihr Schlüssel sehen darf.	Als Abwesenheit behandeln. Kein vorübergehender Fehler.
`conflict`	409	Ein Idempotency-Key wurde mit anderem Rumpf wiederverwendet.	Für eine wirklich neue Anlage einen frischen Schlüssel erzeugen.
`managed_by_import`	409	Der Datensatz gehört einer Importquelle, die dafür maßgeblich ist.	Im System ändern, das den Import speist, nicht hier.
`precondition_failed`	412	If-Match passte nicht zum aktuellen ETag.	Erneut lesen, Änderung erneut anwenden, einmal erneut versuchen.
`payload_too_large`	413	Der Upload überschreitet das Limit dieses Endpunkts.	Vor dem Upload verkleinern. Dieselben Bytes nicht erneut senden.
`unsupported_media_type`	415	Content-Type fehlt oder wird nicht angenommen.	application/json senden, oder multipart/form-data für Uploads.
`validation_failed`	422	Der Rumpf ließ sich lesen, aber ein Feld ist nicht annehmbar.	Das Feld errors lesen; jeder Eintrag nennt ein Feld und den Grund.
`rate_limited`	429	Spitzenlimit überschritten. Das Monatsvolumen weist nicht ab.	Retry-After abwarten, dann mit Streuung erneut versuchen.
`internal_error`	500	Ein Fehler auf unserer Seite.	Mit exponentiell wachsender Wartezeit erneut versuchen. Bei Fortbestehen die request_id nennen.
`service_unavailable`	503	Vorübergehend nicht bedienbar, meist während einer Auslieferung.	Mit wachsender Wartezeit erneut versuchen. Löst sich meist in Sekunden.

Was einen erneuten Versuch wert ist

Die Regel ist einfach, und sie falsch anzuwenden ist die häufigste Art, wie eine Anbindung aus einem kleinen Ausfall einen großen macht.

4xx: nicht erneut versuchen, außer bei 429. Die Anfrage ist falsch, und sie zu wiederholen bleibt falsch. Die Ausnahmen sind 429 und 412, das man nach erneutem Lesen einmal wiederholt.

5xx: erneut versuchen, mit exponentiell wachsender Wartezeit und Streuung, bis zu einem begrenzten Budget. Nie in einer engen Schleife: Ein Dienst, der kämpft, erholt sich langsamer, je stärker man ihn drückt.

Timeouts sind mehrdeutig. Eine Anfrage, die in ein Timeout lief, kann trotzdem ausgeführt worden sein. Genau dafür sind Idempotenzschlüssel bei Schreibvorgängen da.