> Source: https://fiscal.link/integrators/docs/errors
> Ce înseamnă fiecare cod de stare în API-ul local și în API-ul Cloud, cum arată erorile și ce faci la erorile frecvente.

Erori și coduri

# Ce înseamnă fiecare cod.

Ramifică după codul de stare și după \`code\`, unde există, niciodată după text: textele se pot schimba, iar unele vin de la casă, în limba ei.

## API local

Forma erorii: `{ "statusCode": …, "message": "…" }`, plus `code` unde un singur cod de stare acoperă două refuzuri. Niciodată HTML. Excepție: `/api/Receipt` răspunde mereu `200` (vezi „Treci de pe FiscalNet sau Fisco”).

| Status | Cheie în surse | Descriere |
| --- | --- | --- |
| 200 | — | Succes. |
| 400 | — | Cererea încalcă o regulă (interval, lungime, obiect lipsă), sau casa a refuzat comanda („Receipt printing error: …”). Un bon deschis e anulat întâi. |
| 400 | `INVALID_SEPARATING_LINE_TYPE` | Tipul liniei de separare nu e 1–4, sau e 4 pe o casă Datecs. |
| 401 | `LICENSE_REQUIRED` | Casa conectată nu are licență. |
| 403 | `COMMERCE_LICENSE_REQUIRED` | Rutele Shopify fără licența Commerce. |
| 404 | — | Resursa nu există. |
| 424 | — | Transport: nicio casă conectată, sau legătura cu casa a căzut. |
| 500 | — | Casa n-a răspuns la timp: aplicația o marchează „nu răspunde”, iar următorul succes șterge marcajul. Sau o eroare neașteptată în aplicație. |

Coloana „Cheie în surse” numește refuzul în documentația noastră. Câmpul `code` apare în corp doar pe rutele unde un cod de stare acoperă două refuzuri.

```json
{
  "statusCode": 500,
  "message": "Internal server error occurred - if you see this, please contact the developer"
}
```

## API Cloud

Mesajele de eroare sunt text simplu: `text/plain` fără antet `Accept`, sau un șir JSON cu `Accept: application/json`. O cerere care nu se poate citi deloc răspunde `application/problem+json`, cu o hartă `errors`.

| Status | Descriere |
| --- | --- |
| 202 | Comanda e în coadă. |
| 400 | Validarea a eșuat; corpul e mesajul. |
| 401 | Fără cheie, sau cheie necunoscută, revocată ori expirată. Corp gol. |
| 403 | Cheie de alt tip sau a altei organizații. Corp gol. |
| 404 | Nu există în organizația ta; corpul e mesajul. |
| 409 | Conflict cu date existente, de exemplu un nume de client deja folosit. |
| 500 | Eșec neașteptat. Corpul poate fi gol. |

## Rezultatul unei comenzi

O comandă răspunde `202` imediat; rezultatul casei îl citești apoi cu „Starea unei comenzi”: codul în `statusCode`, textul în `message`. Un rezultat reușit e `StatusCode` 200 cu răspunsul în `Data`; o eroare a casei e un obiect cu `statusCode` și `message`.

| `statusCode` | Descriere |
| --- | --- |
| 200 | Succes. |
| 400 | Casa a refuzat, sau corpul încalcă o regulă a aplicației FiscalLink. Majoritatea regulilor se verifică înainte de deschiderea bonului; un bon care eșuează după deschidere e anulat, iar mesajul se termină cu `| Receipt cancelled successfully`. |
| 404 | `unknown_command`: aplicația FiscalLink de pe casă e prea veche pentru această comandă. |
| 409 | La citirea cotelor TVA: verificarea cotelor e oprită pe casă. |
| 424 | Transport: imprimanta nu e conectată sau n-a răspuns la timp. |
| 499 | `client_cancelled`: comanda a fost anulată în timp ce rula. |
| 500 | Eroare neașteptată în aplicație; mesajul numește excepția. Un bon fiscal deja deschis e anulat. |

Erorile pe care aplicația le dă înainte să ajungă la casă au corpuri fixe:

```json
{ "error": "unknown_command", "commandType": "cashRegister.printFiscalReceipt" }
```

```json
{ "error": "invalid_payload", "detail": "<detail>" }
```

```json
{ "error": "internal_error" }
```

```json
{ "error": "client_cancelled" }
```

## Înainte să retrimiți

-   **\`400\`**: cererea a fost refuzată înainte să plece ceva spre casă, sau bonul a fost anulat. Corectează cererea și trimite-o din nou.
-   **\`424\` și timeout (\`500\`) la un bon fiscal**: nu dovedesc că nu s-a tipărit nimic; un document poate exista. Nu retrimite automat. Un bon se trimite din nou doar când știi sigur că nu s-a tipărit, pentru că un bon fiscal dublat nu se mai poate repara.
-   **API-ul Cloud**: fiecare trimitere e o comandă nouă și un bon nou. Când răspunsul unei trimiteri se pierde, interoghează lista comenzilor („Istoricul casei” sau „Toate comenzile”) înainte să trimiți din nou.

## Erori frecvente

| # | Eroare | Ce faci |
| --- | --- | --- |
| 1 | `401` pe API-ul local | Casa nu are licență. Clientul o activează din FiscalLink Cloud (pașii: /app/docs). |
| 2 | `424` | Casa nu e conectată sau legătura a căzut. Clientul verifică conexiunea în aplicația FiscalLink (pașii: /app/docs). |
| 3 | `500` la timeout | Când legătura merge, un timeout înseamnă aproape mereu că, de fapt, casa e în alt mod de lucru. Verifică pe casă, apoi citește „Înainte să retrimiți”. |
| 4 | `400` vânzare liberă pe Daisy | Pornește „Vânzare liberă pe Daisy” (în aplicație sau, ca integrator, în Setări → Date companie) sau vinde articole PLU. |
| 5 | `400` grupă TVA | Folosește o grupă pe care casa o are și care poartă 21%, 11% sau 0%: Tremol 1–6, Datecs 1–7; un Datecs neplătitor de TVA doar 5 și 6. |
| 6 | Casa refuză bonurile după 24 de ore | Casa blochează vânzările la 24 de ore de la prima vânzare fără raport Z (Datecs -111024, Tremol 1100, Daisy 82 „DEPASIT 24h”); pe Datecs, aplicația avertizează după 20 de ore. Trimite raportul Z. |
| 7 | `409` la citirea cotelor TVA | Verificarea cotelor TVA e oprită în aplicația de pe casă. Clientul o pornește din setările aplicației (/app/docs). |
| 8 | `404` la trimiterea unei comenzi Cloud | Casa nu poate primi comenzi: verifică cu „Citește o casă” că e `Active`, că `awaitingClientConsent` e `false` și că abonamentul e activ. |
| 9 | `403` pe API-ul Cloud | Cheia e de alt tip (comenzi, administrare, sandbox) sau `tenantId` nu e organizația cheii. |
| 10 | `unknown_command` | Aplicația FiscalLink de pe casă e prea veche. Clientul o actualizează (/download). |
| 11 | Fără hârtie | Pe API-ul Cloud, bonul se reîncearcă singur la 60 de secunde; interoghează ID-ul inițial. După ce clientul pune hârtie, bonul pleacă. |
| 12 | `Amount must be between 0.01 and 9999999.99. | Receipt cancelled successfully` | Plată automată la un total de 0 sau mai mic, pe Datecs. Verifică liniile bonului. |