Virhekoodit ja virhevastauksen rakenne

1. Jokainen 4xx ja 5xx palauttaa { "error": { type, code, message, param?, doc_url, request_id, errors? } }.
2. Haarauta type-kentän mukaan, kun päätät, onko uudelleenyritys järkevä, ja kuvaa code omaan järjestelmääsi.
3. param osoittaa virheelliseen kenttään, esim. lines.0.vat_rate; errors[] ilmestyy, kun virheitä on useita.
4. Kirjaa request_id jokaisesta virheestä — sen avulla löydämme tarkan pyynnön lokistamme.

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 ja kaksi upstream-tyyppiä ovat uudelleen yritettävissä. authentication_error, permission_error ja invalid_request_error eivät korjaannu uudelleenyrityksellä.
• 404 palautetaan myös toisen tenantin tunnisteelle: emme koskaan vahvista, että jonkun muun tiedot ovat olemassa.
• 409 idempotency_key_reuse tarkoittaa, että käytit avainta eri rungolla. Älä pakota sitä: tarkista, mitä on jo myönnetty.
• Jokaisen virheen doc_url vie suoraan tämän dokumentaation virhe-osioon.
• Viestit ovat romaniaksi, koska API palvelee romanialaista verotuksellista prosessia; älä jäsennä message-kenttää, haarauta code-kentän mukaan.