Gestionare erori

API-ul Qarta utilizează coduri de stare HTTP standard și răspunsuri de eroare pentru a vă ajuta să depanați problemele.

Coduri de stare HTTP

Cod	Sens
200	OK - Cererea a reușit
400	Cerere proastă - Parametri de cerere nevalizi sau corp de cerere malformat
401	Neautorizat - Cheie API lipsă sau invalidă
403	Interzis - Permisiuni insuficiente pentru resursa cerută
500	Eroare server internă - Eroare pe partea serverului

Format răspuns eroare

În funcție de punct final, răspunsurile de eroare urmează unul dintre aceste formate:

Format 1: Răspuns cu mesaj simplu

{
  "message": "Error description"
}

Format 2: Răspuns cu mesaj imbricat

{
  "errorMessage": {
    "message": "Error description"
  }
}

Care puncte finale utilizează care format?

Categoria de punct final	Format de eroare
Puncte finale de portofoliu (acumulare, intrări, puncte, aprovizionare)	Imbricat: { "errorMessage": { "message": "..." } }
Puncte finale de raportare de riscuri (risc punct, risc punct-buffer)	Simplu: { "message": "..." }
Puncte finale de locație (geocodare, completare automată, geocodare inversă)	Simplu: { "message": "..." }
Puncte finale de îmbogățire (unic, lot)	Simplu: { "message": "..." }
Puncte finale WMS / WFS	Răspunsuri de eroare OGC XML sau JSON simplu { "message": "..." }

Gestionare ambelor formate

Pentru a extrage în siguranță mesajul de eroare din orice punct final Qarta, verificați ambele formate:

function getErrorMessage(body) {
  return body?.errorMessage?.message || body?.message || 'Unknown error';
}

Scenarii comune de eroare

400 Cerere proastă

Cauză: Parametri de cerere nevalizi sau corp de cerere malformat

Exemplu:

{
  "errorMessage": {
    "message": "Invalid parameter format"
  }
}

Soluții:

• Verificați că toți parametrii necesari sunt furnizați
• Verificați că tipurile de parametri se potrivesc cu specificația API
• Asigurați-vă că corpul cererii este JSON valid
• Validați că expresiile de filtru și interogările spațiale sunt formatate corect

401 Neautorizat

Cauză: Cheie API lipsă sau invalidă

Soluții:

• Verificați că cheia API este corectă
• Asigurați-vă că antetul Authorization este inclus cu cheia API
• Verificați că cheia API nu a fost revocată în panoul dvs
• Confirmați că cheia API are acces la resursa cerută

403 Interzis

Cauză: Cheia API nu are permisiune să acceseze resursa cerută

Exemple de scenarii:

• Accesarea unui portofoliu pentru care nu aveți permisiune
• Încercarea interogării surselor de date indisponibile pentru contul dvs

Soluții:

• Verificați permisiunile contului dvs în panoul de control
• Verificați că cheia API are acces la portofoliul sau sursa de date
• Contactați suportul dacă credeți că ar trebui să aveți acces

500 Eroare internă a serverului

Cauză: Eroare pe partea serverului

Soluții:

• Reîncercați cererea după o scurtă pauză
• Implementați backoff exponențial pentru reîncercări automate
• Dacă eroarea persistă, contactați suportul cu detalii despre cerere

Strategie de reîncercare

Pentru erorile tranzitorii (coduri de stare 5xx), implementați backoff exponențial:

async function retryRequest(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, options);
      if (response.ok) {
        return response;
      }
      if (response.status >= 500 && i < maxRetries - 1) {
        // Retry on server errors
        const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      return response;
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      const delay = Math.pow(2, i) * 1000;
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

Sfaturi de depanare

• Verificați mai întâi codul de stare HTTP pentru a determina tipul de eroare
• Revizuiți mesajul de eroare pentru detalii specifice despre ce s-a întâmplat
• Verificați cheia API și parametrii cererii
• Pentru erori 500, reîncercați după o scurtă pauză
• Contactați suportul dacă întâmpinați erori persistente