Catalog de erori NextUp

Toate erorile, indiferent de severitate, vin în același envelope cu HTTP 200:

{ "Result": false, "Error": "Mesaj descriptiv în limba română" }

Singura excepție sunt erorile de transport (DNS, firewall, timeout) care nu mai trec de proxy și revin ca HTTP 502 cu corp:

{ "Result": false, "Error": "Proxy error: connect ENETUNREACH 1.2.3.4:8888 - ..." }

Categorii de erori

1. Erori de autentificare

Mesaj	Cauză	Recomandare
AuthenticationToken lipseste, este invalid sau a expirat.	Token absent / format invalid / expirat	Reapelați GetAuthenticationToken.
Invalid credentials.	UserName/Password/Database greșite	Verificați combinația cu cea predefinită în mock.

2. Erori de validare

Mesaj	Cauză	Recomandare
Parametrul "X" este obligatoriu.	Câmp lipsă din Params	Adăugați câmpul. Lista celor obligatorii e în Referința API.
Campul "Method" este obligatoriu.	Envelope-ul nu are Method	Verificați top-level-ul JSON-ului.
Payload-ul nu este JSON valid: ...	JSON malformat	Validați cu un linter.
Comanda trebuie sa contina cel putin o linie.	Lines: []	Adăugați cel puțin o linie cu ArticleCode, Quantity, UnitPrice.
Factura trebuie sa contina cel putin o linie.	Idem	Idem

3. Erori de business (NextUp-specifice)

Acestea sunt erori funcționale ale ERP-ului. Mock Server-ul le reproduce identic.

Cod intern	Mesaj	Cauză	Recomandare
duplicate	Partener cu codul "X" exista deja.	Conflict pe Code la AddPartner	Generați un alt cod sau folosiți AddOrUpdatePartner.
duplicate	Articol cu codul "X" exista deja.	Conflict pe Code la AddArticle	Idem.
not_found	Partenerul cu codul "X" nu a fost gasit.	Lookup pe cod inexistent	Verificați cu GetAllPartners.
not_found	Articol cu codul "X" nu a fost gasit.	Lookup pe cod inexistent	Verificați cu GetAllArticles.
not_found	Cursul valutar pentru simbolul "X" nu este disponibil.	GetExchangeRate cu simbol necunoscut sau dată în viitor	Verificați simbolul (EUR, USD, ...).
missing_vat	Cota TVA cu id X nu exista.	VATRateId invalid la AddArticle	Folosiți unul dintre 1 (19%), 2 (9%), 3 (5%), 4 (0%).
insufficient_stock	Stoc insuficient pentru articolul "X" in depozitul N.	AddSaleInvoice cu cantitate > stoc disponibil	Verificați cu GetStocksForArticleByCode; faceți o intrare cu AddEntryStock întâi.

4. Erori de transport (proxy)

Acestea apar înainte de a ajunge la NextUp ERP. Veniun de la proxy-ul nostru, nu de la ERP.

Mesaj	Cauză	Recomandare
Proxy error: connect ENETUNREACH ...	LAN-ul nu vede ERP-ul	Verificați IP-ul în .env, pingul, firewall-ul. Comutați la mock pentru a continua lucrul.
Proxy error: connect ETIMEDOUT ...	ERP-ul nu răspunde	NextUp e probabil oprit. Pornit prin Utilitare → Servicii WEB → Panou de control → Porneste.
Endpoint-ul "X" nu exista.	URL greșit în client (mock răspunde așa la 404)	Verificați spelling-ul: /NextUpServices/Services/POST/ (cu slash final).
Metoda "X" nu este implementata in mock server.	Numele metodei greșit sau nu există în NextUp	Verificați în Referință API.

HTTP status codes (proxy + mock)

Cod	Când apare	Corpul răspunsului
200	Succes ȘI erori de business (NextUp convention)	{ Result, Error }
400	Headere malformate la proxy	text JSON ad-hoc
404	URL greșit (la mock)	{ Result:false, Error:... }
502	Proxy nu a putut conecta la upstream	{ Result:false, Error:"Proxy error..." }

Niciodată să nu vă bazați pe HTTP status pentru a decide succesul

NextUp returnează mereu 200 când conexiunea a reușit. Singurul indicator real este Result !== false && Error === null. Construiți wrapper-ul SDK-ului dvs. cu această convenție în minte.

Algoritm recomandat pentru tratarea erorilor

Modul "strict" pentru integrări

Pentru integrări critice, recomandăm să aplicați următoarele reguli înainte de a marca un apel "OK":

1. HTTP status === 200
2. body.Error === null (sau lipsește din răspuns)
3. body.Result !== false
4. Pentru Add*, body.Result are forma { Id: number, ... } sau este un number > 0
5. Pentru Update* / Delete*, body.Result === true

Orice abatere de la aceste reguli ar trebui să declanșeze un retry sau un log de severitate ridicată.

Versiunea spec

Mesajele de eroare reproduse aici corespund NextUp v7.47+. Versiuni mai vechi pot folosi mesaje în engleză sau formatări ușor diferite. La integrarea cu ERP-uri vechi, nu faceți matching pe string ci pe substring (error.includes('insufficient')).