Erori și rate limit
Format răspuns eroare
{
"message": "Descriere lizibilă",
"code": "VALIDATION_FAILED"
}
Coduri API (code)
| Cod | HTTP | Semnificație |
|---|---|---|
| UNAUTHORIZED | 401 | Token lipsă/invalid |
| FORBIDDEN | 403 | Fără permisiune / modul dezactivat |
| NOT_FOUND | 404 | Resursă inexistentă |
| VALIDATION_FAILED | 422 | Date invalide |
| COMPANY_REQUIRED | 422 | Lipsește X-Company-Id |
| INSUFFICIENT_STOCK | 422 | Stoc insuficient |
| INVALID_PARTNER | 422 | Partener invalid |
| INVALID_WAREHOUSE | 422 | Depozit invalid |
| INVALID_ARTICLE | 422 | Articol invalid |
| RATE_LIMIT_EXCEEDED | 429 | Prea multe cereri |
| SERVER_ERROR | 500 | Eroare internă |
Rate limiting
| Scope | Limită tipică |
|---|---|
| API per companie | 60 req/min |
| Sandbox 3PL | ~12 req/min |
| GraphQL | limită separată per companie |
| POST /api/auth/token | 10/min per IP |
Header-e utile (când sunt expuse): Retry-After, X-RateLimit-Remaining.
Strategie: exponential backoff + jitter pe 429.
Idempotency
Header Idempotency-Key pe POST — replay safe pentru integrări.
Validare
Erori 422 includ adesea detalii câmp:
{
"message": "The given data was invalid.",
"code": "VALIDATION_FAILED",
"errors": {
"lines.0.quantity": ["Must be greater than 0"]
}
}
Debugging
- Verificați
X-Company-Id - Verificați abilities token
- Verificați modul activ pe companie
- Consultați Jurnal cereri API (UI admin) pentru request_id
Nu logați token-uri complete în sisteme terțe.
Matrice HTTP rapidă
| HTTP | Semnificație | Acțiune integrator |
|---|---|---|
| 200 | OK | Procesați răspunsul |
| 201 | Creat | Salvați ID-ul returnat |
| 401 | Neautentificat | Token invalid/expirat — re-auth |
| 403 | Interzis | Ability sau modul lipsă |
| 404 | Negăsit | Verificați ID / companie |
| 409 | Conflict | Status document invalid |
| 422 | Validare | Citiți errors + code |
| 429 | Rate limit | Backoff + reduceți frecvența |
| 500 | Server | Retry cu backoff; raportați suport |
Depanare pas cu pas
- Confirmați
X-Company-Id—GET /api/companies - Verificați abilities token vs endpoint (ex.
sales-orders:write) - Verificați modul activ pe companie (Intrări/Ieșiri/API)
- Reproduceți în Playground cu același header
- Consultați Jurnal cereri API în UI admin (fără token în ticket)
Sandbox vs producție
Companiile sub furnizor 3PL sandbox au limită redusă (~12 req/min) și pot avea webhooks dezactivate. Nu folosiți token-uri sandbox în ERP producție.