Hibakódok és a hibaboríték

1. Minden 4xx és 5xx ezt adja vissza: { "error": { type, code, message, param?, doc_url, request_id, errors? } }.
2. A type alapján ágazzon el annak eldöntéséhez, hogy van-e értelme az újrapróbálásnak, a code értéket pedig képezze le a saját rendszerére.
3. A param a hibás mezőre mutat, pl. lines.0.vat_rate; az errors[] akkor jelenik meg, ha több ilyen van.
4. Minden hibánál naplózza a request_id értéket — ezzel a naplóinkban pontosan megtaláljuk a kérést.

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

• A rate_limit_error és a két upstream típus újrapróbálható. Az authentication_error, a permission_error és az invalid_request_error nem oldódik meg újrapróbálással.
• 404-et adunk vissza egy másik tenanthoz tartozó id esetén is: soha nem erősítjük meg, hogy más adatai léteznek.
• A 409 idempotency_key_reuse azt jelenti, hogy egy kulcsot eltérő törzzsel használt újra. Ne erőltesse: ellenőrizze, mi lett már kiállítva.
• Minden hibában a doc_url közvetlenül a dokumentáció hibákról szóló részére mutat.
• Az üzenetek románul vannak, mert az API román fiskális folyamatot szolgál ki; ne a message értéket elemezze, hanem a code alapján ágazzon el.