Erori, limite și reluări

O eroare are altă formă decât un răspuns reușit. Nu vine în data; vine ca application/problem+json, după RFC 9457, cu un type stabil pe care poți ramifica.

{
  "type": "urn:fgo:api:v2:problem:validation",
  "title": "Cererea nu a trecut validarea.",
  "status": 400,
  "detail": "Corectati campurile indicate in validation_errors si retrimiteti cererea.",
  "instance": "urn:trace:00-8f3a1c2e6b7d4e219c0a2f1d3e4b5a6c-5f2a9c1d3e4b6a7c-01",
  "meta": { "timestamp": "2026-09-03T12:00:00+03:00" },
  "validation_errors": [
    {
      "location": "body",
      "pointer": "/articole",
      "issues": [
        { "code": "invalid_value", "message": "Campul 'articole' trebuie sa contina cel putin un articol." }
      ]
    }
  ]
}

Ramifică pe type și pe status. title și detail sunt pentru oameni și se pot schimba fără o versiune nouă.

Categoriile

validation_errors

Apare numai pe validation și spune exact ce e greșit, câmp cu câmp. Fiecare element are location — body, query, path, header — și, după caz, pointer (JSON Pointer în corp, ca /articole/0/cota_tva) sau name (numele parametrului sau al headerului). issues are codul stabil al problemei și un mesaj.

Codurile din issues[].code sunt extensibile: pot apărea coduri noi. Pentru un cod necunoscut, tratează răspunsul ca eroare de validare și folosește mesajul pentru diagnosticare. Codurile existente sunt:

De exemplu, o serie de storno prea lungă:

{ "code": "out_of_range", "message": "Dimensiunea valorii transmise pentru 'serie_storno' nu trebuie sa depaseasca 50 caractere.", "args": { "max_length": 50, "length": 60 } }

O cerere cu trei câmpuri greșite primește un singur 400 cu trei elemente, nu trei runde de încercări.

Validarea e strictă în amândouă direcțiile: un parametru de query sau o proprietate JSON pe care nu o documentăm e 400, nu e ignorată. Așa afli de o greșeală de tastare din prima, nu după ce filtrul „n-a mers".

motiv

Pe 403 și pe invalid-state, motiv.cod spune de ce:

{
  "type": "urn:fgo:api:v2:problem:forbidden",
  "status": 403,
  "detail": "Nu ai suficiente drepturi, vezi motiv.",
  "motiv": { "cod": "drept_lipsa", "mesaj": "Cheia API nu are dreptul de a face aceasta operatie." }
}

De exemplu, o emitere oprită de verificarea duplicatelor:

{
  "type": "urn:fgo:api:v2:problem:invalid-state",
  "title": "Starea curenta nu permite operatia",
  "status": 400,
  "detail": "Factura FGO 1201 exista deja salvata.",
  "instance": "urn:trace:00-8f3a1c2e6b7d4e219c0a2f1d3e4b5a6c-5f2a9c1d3e4b6a7c-01",
  "meta": { "timestamp": "2026-09-03T12:00:00+03:00" },
  "motiv": {
    "cod": "factura_duplicata",
    "mesaj": "Factura FGO 1201 exista deja salvata."
  }
}

Criteriile verificării sunt descrise în Emiterea unei facturi.

Codurile din motiv.cod sunt extensibile. Pentru un cod necunoscut, tratează refuzul folosind status și type, fără să presupui că operația a reușit.

Limitele de apeluri

Fiecare operație acceptă un apel la un interval fix, pe firmă. A doua cerere pe aceeași operație, înainte să treacă intervalul, primește 429. Operațiile diferite nu se influențează: poți citi articolele și gestiunile în aceeași secundă. Intervalele, pe fiecare operație:

Aceleași intervale sunt scrise și în referință, la răspunsul 429 al fiecărei operații. Listele paginate nu au un interval separat pentru pagini: fiecare pagină e un apel, la o secundă de precedenta.

Limitele se pot modifica. La depășirea limitei, răspunsul indică timpul de așteptare:

HTTP/1.1 429 Too Many Requests
Retry-After: 1

Așteaptă cel puțin numărul de secunde din Retry-After înainte de a reîncerca. Pentru apeluri în lot, respectă intervalul operației și ajustează pauza după acest header.

Ce reîncerci și ce nu

Citirile (GET) se reîncearcă în siguranță. La 5xx, reîncearcă de câteva ori cu pauză crescătoare — o secundă, două, patru — apoi oprește-te.

Scrierile nu se reîncearcă automat, decât acolo unde documentația operației spune că e sigur. Atașarea AWB-ului e idempotentă: același AWB de două ori lasă factura în aceeași stare. Emiterea nu e: fiecare apel reușit produce o factură. Ce faci când nu primești răspuns la emitere e descris în Emiterea unei facturi.

La 429 sau 503 maintenance returnat de FGO API, reîncearcă după intervalul indicat de Retry-After: cererea nu a fost procesată. 503 maintenance înseamnă mentenanță planificată: documentația rămâne disponibilă, API-ul nu. Pentru un alt răspuns 503, inclusiv unul generat de un proxy, nu presupune că cererea nu a fost procesată; aplică regulile de reluare ale operației.

Identificarea unei cereri

Fiecare răspuns conține headerul x-fapi-interaction-id, identificatorul cererii:

x-fapi-interaction-id: 7b0f11d5-6e52-4b57-beca-15f47bf3f808

UUID (numit și GUID) este un identificator de 128 de biți, definit de RFC 9562. Folosește forma cu cratime din exemplu. Poți trimite tu un UUID în acest header; dacă lipsește sau nu este valid, îl generăm noi și îl întoarcem în răspuns. Păstrează-l în logurile tale.

Când semnalezi o problemă suportului, trimite valorile headerelor Server-Timing și x-fapi-interaction-id din răspunsul primit. Dacă nu ai primit niciun răspuns, trimite UUID-ul generat de tine.