Chybové kódy a chybová obálka

1. Každá 4xx a 5xx vracia { "error": { type, code, message, param?, doc_url, request_id, errors? } }.
2. Vetvite podľa type, aby ste rozhodli, či má opakovanie zmysel, a code mapujte do vlastného systému.
3. param ukazuje na chybné pole, napr. lines.0.vat_rate; errors[] sa objaví, keď ich je viac.
4. Pri každej chybe logujte request_id — umožní nám nájsť presne danú požiadavku v našich logoch.

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 a dva typy upstream sa dajú opakovať. authentication_error, permission_error a invalid_request_error sa opakovaním nevyriešia.
• 404 sa vracia aj pre id, ktoré patrí inému tenantovi: nikdy nepotvrdzujeme, že cudzie údaje existujú.
• 409 idempotency_key_reuse znamená, že ste znovu použili kľúč s iným telom. Nevynucujte to: overte, čo už bolo vystavené.
• doc_url v každej chybe smeruje priamo na sekciu chýb v tejto dokumentácii.
• Správy sú v rumunčine, pretože API slúži rumunskému fiškálnemu toku; neparsujte message, vetvite podľa code.