Coduri de eroare și envelope-ul de eroare

1. Orice 4xx sau 5xx întoarce { "error": { type, code, message, param?, doc_url, request_id, errors? } }.
2. Ramifică pe type ca să decizi dacă are sens un retry, și mapează code în propriul tău sistem.
3. param arată câmpul vinovat, ca lines.0.vat_rate; errors[] apare când sunt mai multe.
4. Loghează request_id la fiecare eroare — cu el găsim requestul exact în logurile noastre.

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 cele două tipuri de upstream se pot reîncerca. authentication_error, permission_error și invalid_request_error nu se rezolvă prin retry.
• 404 apare și pentru un id care aparține altui tenant: nu confirmăm niciodată existența datelor altcuiva.
• 409 idempotency_key_reuse înseamnă că ai refolosit o cheie cu un body diferit. Nu forța: verifică ce s-a emis deja.
• doc_url din fiecare eroare trimite direct în secțiunea de erori a acestei documentații.
• Mesajele sunt în română, pentru că API-ul deservește un flux fiscal românesc; nu parsa message, ramifică pe code.