Fehlercodes und der Fehlerumschlag

1. Jede 4xx- und 5xx-Antwort liefert { "error": { type, code, message, param?, doc_url, request_id, errors? } }.
2. Verzweigen Sie nach type, um zu entscheiden, ob ein Retry sinnvoll ist, und bilden Sie code in Ihr eigenes System ab.
3. param zeigt auf das fehlerhafte Feld, z. B. lines.0.vat_rate; errors[] erscheint, wenn es mehrere gibt.
4. Protokollieren Sie request_id bei jedem Fehler – damit finden wir die exakte Anfrage in unseren Logs.

json
{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_failed",
    "message": "Datele trimise nu sunt valide.",
    "param": "lines.0.vat_rate",
    "doc_url": "https://4invoices.net/ro/api-dezvoltatori#errors",
    "request_id": "req_8a893f2f33d4472da8d6e144",
    "errors": [
      { "param": "lines.0.vat_rate", "message": "VAT rate must be a percent (21), not a fraction", "type": "value_error" }
    ]
  }
}

https://api.4invoices.net/v1 · https://api.4invoices.net/v1/openapi.json

• rate_limit_error und die beiden upstream-Typen sind wiederholbar. authentication_error, permission_error und invalid_request_error lassen sich durch einen Retry nicht beheben.
• Ein 404 kommt auch für eine id zurück, die zu einem anderen Mandanten gehört: Wir bestätigen nie, dass Daten eines anderen existieren.
• 409 idempotency_key_reuse bedeutet, dass Sie einen Schlüssel mit einem anderen Body wiederverwendet haben. Erzwingen Sie nichts: Prüfen Sie, was bereits ausgestellt wurde.
• Die doc_url in jedem Fehler verweist direkt auf den Fehlerabschnitt dieser Dokumentation.
• Die Meldungen sind auf Rumänisch, weil die API einen rumänischen Fiskalprozess bedient; parsen Sie nicht message, sondern verzweigen Sie nach code.