> ## Documentation Index
> Fetch the complete documentation index at: https://docs.windsurf.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Gestionarea erorilor

> Mesaje de eroare frecvente și recomandări de depanare pentru Analytics API, inclusiv erori de autentificare, structura interogărilor și limitare a ratei de solicitări.

<div id="overview">
  ## Prezentare generală
</div>

Analytics API returnează mesaje de eroare detaliate pentru a facilita depanarea interogărilor nevalide. Această pagină prezintă scenarii de eroare frecvente și modul de rezolvare a acestora.

<div id="error-response-format">
  ## Formatul răspunsului de eroare
</div>

Când apare o eroare, API-ul returnează un răspuns de eroare cu un mesaj descriptiv:

```json theme={null}
{
  "error": "Mesaj de eroare care descrie ce nu a funcționat"
}
```

<div id="common-errors">
  ## Erori comune
</div>

<div id="authentication-errors">
  ### Erori de autentificare
</div>

<AccordionGroup>
  <Accordion title="Cheie de serviciu invalidă">
    **Eroare:** `Invalid service key`

    **Cauză:** Cheia de serviciu furnizată nu este validă sau a fost revocată.

    **Soluție:**

    * Verificați dacă cheia de serviciu este corectă
    * Verificați dacă cheia de serviciu nu a fost revocată
    * Generați o nouă cheie de serviciu, dacă este necesar
  </Accordion>

  <Accordion title="Permisiuni insuficiente">
    **Eroare:** `Insufficient permissions`

    **Cauză:** Cheia de serviciu nu are permisiunile necesare pentru endpoint-ul pe care îl apelați.

    **Soluție:**

    * Actualizați permisiunile cheii de serviciu în setările echipei
    * Consultați secțiunea [Introducere în API](/ro/plugins/accounts/api-reference/api-introduction#required-permissions) pentru permisiunea specifică necesară fiecărui endpoint
  </Accordion>
</AccordionGroup>

<div id="query-structure-errors">
  ### Erori de structură a interogării
</div>

<AccordionGroup>
  <Accordion title="Lipsesc selections">
    **Eroare:** `at least one field or aggregation is required`

    **Cauză:** Cererea de interogare nu conține niciun selections sau aggregations.

    **Soluție:** Adăugați cel puțin un element în selections în cererea de interogare:

    ```json theme={null}
    "selections": [
      {
        "field": "num_acceptances",
        "aggregation_function": "QUERY_AGGREGATION_SUM"
      }
    ]
    ```
  </Accordion>

  <Accordion title="data_source invalid">
    **Eroare:** `invalid query table: QUERY_DATA_SOURCE_UNSPECIFIED`

    **Cauză:** Probabil există o greșeală de tastare în câmpul `data_source`.

    **Soluție:** Verificați încă o dată scrierea valorii din data\_source. Opțiuni valide:

    * `QUERY_DATA_SOURCE_USER_DATA`
    * `QUERY_DATA_SOURCE_CHAT_DATA`
    * `QUERY_DATA_SOURCE_COMMAND_DATA`
    * `QUERY_DATA_SOURCE_PCW_DATA`
  </Accordion>

  <Accordion title="Funcții de agregare amestecate">
    **Eroare:** `all selection fields should have an aggregation function, or none of them should`

    **Cauză:** Unele selections au funcții de agregare, iar altele nu.

    **Soluție:** Adăugați funcții de agregare pentru toate entries din selections sau eliminați-le pe toate:

    **Invalid:**

    ```json theme={null}
    "selections": [
      {
        "field": "num_acceptances",
        "aggregation_function": "QUERY_AGGREGATION_SUM"
      },
      {
        "field": "num_lines_accepted",
        "aggregation_function": "QUERY_AGGREGATION_UNSPECIFIED"
      }
    ]
    ```

    **Valid:**

    ```json theme={null}
    "selections": [
      {
        "field": "num_acceptances",
        "aggregation_function": "QUERY_AGGREGATION_SUM"
      },
      {
        "field": "num_lines_accepted",
        "aggregation_function": "QUERY_AGGREGATION_SUM"
      }
    ]
    ```
  </Accordion>
</AccordionGroup>

<div id="field-and-aggregation-errors">
  ### Erori de câmp și agregare
</div>

<AccordionGroup>
  <Accordion title="Funcție de agregare nevalidă">
    **Eroare:** `invalid aggregation function for string type field ide: QUERY_AGGREGATION_SUM`

    **Cauză:** Funcția de agregare nu este compatibilă cu tipul de câmp specificat.

    **Soluție:** Consultă secțiunea [Available Fields](/ro/plugins/accounts/api-reference/custom-analytics#available-fields) pentru a vedea ce funcții de agregare sunt valide pentru fiecare câmp. Câmpurile de tip șir acceptă, de obicei, doar `COUNT` și `UNSPECIFIED`.
  </Accordion>

  <Accordion title="Agregare pe câmp distinct">
    **Eroare:** `tried to aggregate on a distinct field: distinct_developer_days. Consider aggregating on the non-distinct fields instead: [api_key date]`

    **Cauză:** Câmpurile cu modelul „distinct\_\*” nu pot fi folosite în secțiunea aggregations.

    **Soluție:** Utilizează câmpurile alternative sugerate pentru agregare:

    **Invalid:**

    ```json theme={null}
    "aggregations": [
      {
        "field": "distinct_developer_days",
        "name": "distinct_developer_days"
      }
    ]
    ```

    **Valid:**

    ```json theme={null}
    "aggregations": [
      {
        "field": "api_key",
        "name": "api_key"
      },
      {
        "field": "date",
        "name": "date"
      }
    ]
    ```
  </Accordion>

  <Accordion title="Aliasuri de câmp duplicate">
    **Eroare:** `duplicate field alias for selection/aggregation: num_acceptances`

    **Cauză:** Mai multe selections sau aggregations au același nume.

    **Soluție:** Asigură-te că toate aliasurile de câmp sunt unice. Reține că, dacă nu este specificat niciun nume, valoarea implicită este `{aggregation_function}_{field_name}`.
  </Accordion>
</AccordionGroup>

<div id="data-filtering-errors">
  ### Erori de filtrare a datelor
</div>

<AccordionGroup>
  <Accordion title="Nume de grup invalid">
    **Eroare:** `invalid group name: GroupName`

    **Cauză:** Numele de grup specificat nu există în organizația ta.

    **Soluție:**

    * Verifică încă o dată ortografia numelui de grup
    * Verifică dacă grupul există în setările echipei
    * Folosește exact numele de grup așa cum apare în tabloul de bord al echipei
  </Accordion>

  <Accordion title="Format de timestamp invalid">
    **Eroare:** `invalid timestamp format`

    **Cauză:** Marcajul temporal (timestamp) nu este în formatul corect RFC 3339.

    **Soluție:** Folosește formatul corect pentru marcajul temporal:

    ```
    2023-01-01T00:00:00Z
    ```

    **Exemple valide:**

    * `2024-01-01T00:00:00Z`
    * `2024-12-31T23:59:59Z`
    * `2024-06-15T12:30:45Z`
  </Accordion>

  <Accordion title="Filtre în conflict">
    **Eroare:** `Cannot use both group_name and emails parameters`

    **Cauză:** Au fost furnizați atât parametrii `group_name`, cât și `emails` într-o cerere Cascade Analytics.

    **Soluție:** Folosește fie `group_name`, fie `emails`, dar nu pe ambele:

    **Invalid:**

    ```json theme={null}
    {
      "group_name": "engineering",
      "emails": ["user@example.com"]
    }
    ```

    **Valid:**

    ```json theme={null}
    {
      "group_name": "engineering"
    }
    ```

    **Sau:**

    ```json theme={null}
    {
      "emails": ["user@example.com", "user2@example.com"]
    }
    ```
  </Accordion>
</AccordionGroup>

<div id="rate-limiting">
  ## Limitarea ratei
</div>

<AccordionGroup>
  <Accordion title="Limită de rată depășită">
    **Eroare:** `429 Too Many Requests`

    **Cauză:** Ai depășit limita de rată a API-ului.

    **Soluție:**

    * Așteaptă înainte de a trimite solicitări suplimentare
    * Implementează backoff exponențial în client
    * Ia în considerare gruparea mai multor interogări într-o singură solicitare, acolo unde este posibil
    * Contactează echipa de asistență dacă ai nevoie de limite de rată mai mari
  </Accordion>
</AccordionGroup>

<div id="debugging-tips">
  ## Sfaturi de depanare
</div>

<div id="1-start-simple">
  ### 1. Începeți simplu
</div>

Începeți cu întrebări de bază și adăugați treptat complexitate:

```json theme={null}
{
  "service_key": "cheia_ta",
  "query_requests": [
    {
      "data_source": "QUERY_DATA_SOURCE_USER_DATA",
      "selections": [
        {
          "field": "num_acceptances",
          "aggregation_function": "QUERY_AGGREGATION_COUNT"
        }
      ]
    }
  ]
}
```

<div id="2-validate-field-names">
  ### 2. Validați numele câmpurilor
</div>

Verificați încă o dată numele câmpurilor în documentația [Available Fields](/ro/plugins/accounts/api-reference/custom-analytics#available-fields).

<div id="3-check-aggregation-compatibility">
  ### 3. Verifică compatibilitatea agregărilor
</div>

Asigură-te că funcțiile de agregare sunt compatibile cu tipurile de câmp selectate.

<div id="4-test-filters-separately">
  ### 4. Testează filtrele separat
</div>

Dacă interogarea nu returnează rezultatele așteptate, încearcă să elimini filtrele pe rând pentru a izola problema.

<div id="5-use-proper-json-formatting">
  ### 5. Folosește o formatare JSON corectă
</div>

Asigură-te că JSON-ul este formatat corect și că toate șirurile sunt citate corect.

<div id="getting-help">
  ## Obținerea de ajutor
</div>

Dacă întâmpini în continuare probleme:

1. **Verifică atent mesajul de eroare** - Majoritatea erorilor includ îndrumări specifice despre cum să remediezi problema
2. **Consultă exemplele** - Compară structura interogării tale cu exemplele funcționale din documentație
3. **Contactează asistența** - Ia legătura cu [Windsurf Support](https://windsurf.com/support) și include mesajul de eroare specific și interogarea ta

<div id="api-version-notes">
  ## Note despre versiunea API
</div>

Gestionarea erorilor și validarea au fost îmbunătățite în versiunile API 1.10.0 și ulterioare. Dacă folosiți o versiune mai veche, luați în considerare actualizarea pentru a obține mesaje de eroare mai detaliate.