Gestionarea erorilor (Error Handling)

API-ul pentru Parteneri utilizează coduri de stare HTTP standard și returnează răspunsuri JSON de eroare consistente.

Formatul răspunsului de eroare

Toate erorile urmează această structură:

{
	"statusCode": 400,
	"message": "Validation failed",
	"error": "Bad Request"
}

Coduri de stare

Cod	Eroare	Descriere
`400`	Bad Request	Corp de cerere invalid, câmpuri obligatorii lipsă sau eroare de validare
`401`	Unauthorized	Credențiale de autentificare lipsă, invalide sau expirate
`403`	Forbidden	Credențiale valide, dar permisiuni insuficiente pentru această acțiune
`404`	Not Found	Resursa solicitată nu există
`409`	Conflict	Cerere duplicată detectată (de ex., cheie de idempotență duplicată cu payload diferit)
`429`	Too Many Requests	Limita de rată depășită
`500`	Internal Server Error	A apărut o eroare neașteptată pe server

Erori de validare

Pentru erorile 400 cauzate de validarea cererii, câmpul message poate conține detalii despre câmpurile care nu au trecut validarea:

{
	"statusCode": 400,
	"message": [
		"products.0.productId must be a UUID",
		"products.0.startAt must be a valid ISO 8601 date",
		"payment.type must be one of: CARD, GOOGLE_PAY, APPLE_PAY, IDEAL, REVOLUT, BANCONTACT"
	],
	"error": "Bad Request"
}

Bune practici

Verificați întotdeauna câmpul statusCode pentru a determina categoria erorii.
Pentru erorile 401, verificați cheia API, actualitatea mărcii temporale (în interval de 5 minute), unicitatea nonce-ului și calculul semnăturii.
Pentru erorile 409 la crearea comenzilor, comanda originală a fost deja procesată. Recuperați-o utilizând cheia de idempotență sau referința externă.
Pentru erorile 500, reîncercați cu backoff exponențial. Dacă eroarea persistă, contactați suportul.