Kody błędów i koperta błędu

1. Każdy 4xx i 5xx zwraca { "error": { type, code, message, param?, doc_url, request_id, errors? } }.
2. Rozgałęziaj logikę według type, aby zdecydować, czy ponowienie ma sens, a code mapuj na własny system.
3. param wskazuje błędne pole, np. lines.0.vat_rate; errors[] pojawia się, gdy jest ich kilka.
4. Loguj request_id przy każdym błędzie — pozwala nam znaleźć dokładnie to żądanie w naszych logach.

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 i dwa typy upstream można ponawiać. authentication_error, permission_error i invalid_request_error nie znikną po ponowieniu.
• 404 jest zwracane także dla id należącego do innego tenanta: nigdy nie potwierdzamy, że cudze dane istnieją.
• 409 idempotency_key_reuse oznacza, że użyto ponownie klucza z inną treścią. Nie wymuszaj: sprawdź, co zostało już wystawione.
• doc_url w każdym błędzie prowadzi bezpośrednio do sekcji błędów tej dokumentacji.
• Komunikaty są po rumuńsku, ponieważ API obsługuje rumuński obieg fiskalny; nie parsuj message, rozgałęziaj według code.