Codici di errore e involucro dell'errore

1. Ogni risposta 4xx e 5xx restituisce { "error": { type, code, message, param?, doc_url, request_id, errors? } }.
2. Ramifica la logica su type per decidere se ha senso ritentare, e mappa code nel tuo sistema.
3. param indica il campo problematico, ad es. lines.0.vat_rate; errors[] compare quando ce ne sono più di uno.
4. Registra request_id per ogni errore: ci permette di trovare la richiesta esatta nei nostri log.

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 e i due tipi upstream si possono ritentare. authentication_error, permission_error e invalid_request_error non si risolvono ritentando.
• Un 404 viene restituito anche per un id che appartiene a un altro tenant: non confermiamo mai l’esistenza dei dati di qualcun altro.
• 409 idempotency_key_reuse significa che hai riutilizzato una chiave con un body diverso. Non forzare: verifica cosa è già stato emesso.
• La doc_url di ogni errore rimanda direttamente alla sezione degli errori di questa documentazione.
• I messaggi sono in rumeno perché l’API serve un flusso fiscale rumeno; non analizzare message, ramifica la logica su code.