Umgang mit API-Fehlercodes

Wenn Sie die API von Cord integrieren, lohnt es sich, fehlgeschlagene Antworten sauber zu behandeln, um eine gute Nutzererfahrung zu bieten.

Aufbau eines Fehlers

Fehlgeschlagene Antworten liefern ein flaches JSON-Objekt mit zwei Feldern:

{
  "error": "Company name is required",
  "code": "invalid_request"
}

• error: eine lesbare Meldung, die Sie anzeigen oder protokollieren können.
• code: ein stabiler Bezeichner, auf den Sie in Ihrem Code verzweigen können (z. B. invalid_json, invalid_request).

Häufige HTTP-Codes

• 400 Bad Request: Ein Parameter fehlt oder das JSON ist fehlerhaft (code: "invalid_request" oder "invalid_json").
• 401 Unauthorized: Ihr API-Schlüssel ist ungültig oder widerrufen, Sie haben den Header Authorization nicht gesendet ("invalid_key", "missing_key"), oder der Schlüssel ist abgelaufen ("key_expired").
• 402 Payment Required: Ihr Abonnement hat die Anzahl der im Tarif enthaltenen API-Schlüssel erreicht ("subscription_key_limit"); widerrufen Sie einen älteren Schlüssel oder wechseln Sie in einen höheren Tarif.
• 403 Forbidden: Ihrem Schlüssel fehlt der nötige Geltungsbereich (z. B. bei einem reinen Leseschlüssel für einen POST, Code "insufficient_scope"), ein eingeschränkter Schlüssel hat keine Berechtigung für diese Ressource ("insufficient_permissions"), der Schlüssel hat erlaubte IP-Adressen und die Anfrage kam von einer anderen ("ip_not_allowed"), oder ein veröffentlichbarer Schlüssel wird von einer nicht autorisierten Herkunft/Domain verwendet ("unauthorized_origin", "missing_origin").
• 404 Not Found: Die Ressource existiert nicht oder gehört nicht zu Ihrer Organisation.
• 409 Conflict: Die Aktion passt nicht zum aktuellen Status der Ressource – wer zum Beispiel eine Rechnung storniert, auf die bereits Zahlungen angerechnet wurden, erhält 409 mit code: "credit_note_required": Das richtige Dokument ist eine Gutschrift.
• 413/415: Der Anfragetext überschreitet die Größenobergrenze ("payload_too_large") oder wird nicht als application/json gesendet ("unsupported_media_type").
• 429 Too Many Requests: Sie haben das Anfragelimit oder das monatliche Kontingent Ihres Tarifs überschritten ("api_quota_exceeded"). Siehe Anfragelimits.
• 500 Internal Server Error: ein Fehler auf unserer Seite (selten; wenden Sie sich an den Support, wenn er bestehen bleibt).
• 502/503: Der externe Anbieter, von dem der Vorgang abhängt, hat nicht geantwortet – wer zum Beispiel eine Rechnung stempelt, ohne den Wechselkurs belegen zu können, erhält 503 mit code: "fx_unavailable", statt dass ein Kurs erfunden wird (siehe die Wechselkursrichtlinie in der Dokumentation zur Rechnungsstellung).

Hinweis: Die API v1 verarbeitet Kartenzahlungen nicht direkt; das geschieht im öffentlichen Link von Cord. Deshalb sehen Sie in diesen Antworten keine Fehler wegen abgelehnter Karten.