API — Erori

Format eroare

Toate erorile returnează JSON cu același format:

{
  "statusCode": 401,
  "code": "API_KEY_INVALID",
  "message": "Invalid or revoked API key"
}

Pentru erori de validare cu multiple câmpuri:

{
  "statusCode": 400,
  "code": "VALIDATION_ERROR",
  "message": "Validare eșuată",
  "details": [
    { "field": "cpvCodes", "message": "Formatul codului CPV este invalid" },
    { "field": "minValue", "message": "Valoarea minimă trebuie să fie pozitivă" }
  ]
}

---

Coduri de status HTTP

Cod	Semnificație	Cauze frecvente
400	Bad Request	Body invalid, parametri malformați, limite depășite
401	Unauthorized	API Key sau JWT lipsă, invalid sau revocat
402	Payment Required	Credite API epuizate pentru luna curentă
403	Forbidden	Plan insuficient sau companie din alt tenant
404	Not Found	Resursa nu există sau nu aparține contului tău
409	Conflict	Resursa există deja (ex: watchlist cu același nume)
410	Gone	Token de descărcare expirat sau depășit numărul maxim de utilizări
422	Unprocessable Entity	Date valide sintactic dar invalide semantic
429	Too Many Requests	Rate limit depășit — verifică Retry-After
500	Internal Server Error	Eroare internă — raportează la suport dacă persistă
503	Service Unavailable	Serviciu temporar indisponibil — aplică retry cu backoff

---

Erori API Key (401 / 403)

Cod eroare	Status	Cauză
API_KEY_MISSING	401	Antetul Authorization: Bearer lipsește
API_KEY_INVALID	401	Cheia nu există sau nu a fost recunoscută
API_KEY_REVOKED	401	Cheia a fost revocată din Settings → API
PLAN_UPGRADE_REQUIRED	403	Plan < Consultant; necesari 349 RON/lună
COMPANY_ACCESS_DENIED	403	companyId nu aparține tenant-ului cheii tale

{
  "statusCode": 401,
  "code": "API_KEY_REVOKED",
  "message": "Invalid or revoked API key"
}

---

Erori credite (402)

Cod eroare	Status	Cauză
API_CREDITS_EXHAUSTED	402	Credite epuizate pentru luna curentă

{
  "statusCode": 402,
  "code": "API_CREDITS_EXHAUSTED",
  "message": "Creditele API incluse în planul Consultant au fost epuizate pentru această lună.",
  "credits_remaining": 0,
  "credits_required": 20,
  "period_ends_at": "2026-07-01T00:00:00+03:00"
}

---

Erori de validare și limite (400 / 422)

Cod eroare	Status	Cauză
DATE_RANGE_EXCEEDED	400	Intervalul to - from depășește 90 de zile
LIMIT_EXCEEDED	400	limit > 1000 la export
WEBHOOK_LIMIT_EXCEEDED	422	Deja 5 webhooks active per tenant

---

Token descărcare expirat (410)

Cod eroare	Status	Cauză
DOWNLOAD_TOKEN_EXPIRED	410	Token > 15 min sau folosit de mai mult de 3 ori

---

Rate limiting (429)

Cod eroare	Status	Cauză
RATE_LIMIT_EXCEEDED	429	Limita de req/min sau req/oră depășită

{
  "statusCode": 429,
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "Rate limit depășit.",
  "retry_after_seconds": 23
}

Limitele pe grup de endpoint:

Grup	Limită
General (/tenders, webhooks)	60 / minut
Export (/export/tenders)	20 / oră
PDF reports	10 / oră

---

Strategie de retry recomandată

Cod	Retry?	Strategie
400	Nu	Corectează request-ul înainte de a reîncerca
401	Da*	API Key — verifică dacă a fost revocat; JWT — reînnoiește token-ul
402	Nu	Creditele se resetează la 1 ale lunii
403	Nu	Verifică plan sau companyId
404	Nu	Verifică ID-ul resursei
410	Nu	Solicită un nou URL de descărcare (/jobs/:id/download)
429	Da	Așteaptă retry_after_seconds, apoi retrimitere
500	Da	Exponential backoff: 1s, 2s, 4s, max 3 încercări
503	Da	Exponential backoff: 5s, 10s, 20s, max 3 încercări

---

Logging recomandat

Loghează întotdeauna:

• statusCode și code din răspunsul de eroare
• X-Request-Id din antet (util pentru suport)
• Timestamp-ul și endpoint-ul accesat

Nu loga: API Key, token-uri JWT, parole sau payload-uri complete ale utilizatorilor.

Vezi și

• Autentificare API Key
• Credite API
• Referință API — overview