Referencia chýb API

Táto príručka zdokumentuje všetky kódy chýb, formáty odoziev a kroky na riešenie problémov pre API TeamDay.

---

Formát chybovej odozvy

Všetky chyby API sa riadia konzistentnou štruktúrou JSON:

{
  "error": true,
  "statusCode": 400,
  "statusMessage": "Bad Request",
  "message": "Podrobný popis chyby"
}

Polia:

• error (boolean) - Vždy true pre chybové odozvy
• statusCode (number) - HTTP stavový kód
• statusMessage (string) - Čitateľný stav
• message (string) - Podrobné vysvetlenie chyby

---

HTTP stavové kódy

2xx Úspech

Toto nie sú chyby, ale úspešné odozvy:

200 OK

Význam: Požiadavka bola úspešná

Používané v:

• Požiadavky GET (zoznam, získanie podrobností)
• Požiadavky PATCH (aktualizácia)
• Požiadavky DELETE (měkké vymazanie)
• Požiadavky POST (zrušenie vykonávania)

Príklad:

{
  "id": "agent_abc123",
  "name": "Pomocník pre výskum",
  "...": "..."
}

201 Vytvorené

Význam: Prostredok bol úspešne vytvorený

Používané v:

• Požiadavky POST (vytvorenie agenta, úlohy)

Príklad:

{
  "id": "agent_abc123",
  "name": "Pomocník pre výskum",
  "createdAt": "2025-12-09T10:00:00Z",
  "...": "..."
}

---

4xx Chyby klienta

Tieto chyby naznačujú problémy s požiadavkou.

400 Chybná požiadavka

Význam: Neplatné parametre požiadavky alebo chýbajúce povinné polia

Bežné príčiny:

• Chýbajúce povinné polia
• Neplatné hodnoty polí
• Malformovaný JSON
• Neplatné parametre dotazu

Príklady:

Chýbajúce povinné pole:

{
  "error": true,
  "statusCode": 400,
  "statusMessage": "Bad Request",
  "message": "Missing required field: name"
}

Neplatná hodnota viditeľnosti:

{
  "error": true,
  "statusCode": 400,
  "statusMessage": "Bad Request",
  "message": "Invalid visibility value. Must be: private, organization, or public"
}

Ako opraviť:

1. Skontrolujte, či telo požiadavky zodpovedá dokumentácii API
2. Potvrďte, že sú prítomné všetky povinné polia
3. Overte, že hodnoty polí sú platné (výčty, typy)
4. Otestujte syntax JSON pomocou validátora

---

401 Neoprávnené

Významnosť: Autentifikácia zlyhala alebo chýba

Bežné príčiny:

• Chýbajúca hlavička Authorization
• Neplatný token
• Expirovaný token
• Nesprávny formát tokenu

Ako opraviť:

1. Skontrolujte, či je prítomná hlavička Authorization
2. Overte hlavičku formát: Authorization: Bearer td_xxxxx...
3. Potvrďte, že token nie je expirovaný v Nastaveniach → Prístup API
4. Vygenerujte nový token, ak je potrebný
5. Skontrolujte, či bol token skopírovaný správne (bez extra medzier)

---

403 Zakázané

Zmyslenie: Autentifikovaný, ale nie oprávnené na túto akciu

Bežné príčiny:

• Používateľ nemá požadované povolenia
• Prístup organizácie bol odvolaný
• Prostredok patrí inej organizácii

Príklad:

{
  "error": true,
  "statusCode": 403,
  "statusMessage": "Forbidden",
  "message": "You don't have permission to access this resource"
}

Ako opraviť:

1. Overte, že používateľ má správnu rolu/povolenia
2. Skontrolujte, že používateľ stále patrí do organizácie
3. Potvrďte, že prostredok patrí vašej organizácii
4. Kontaktujte administrátora organizácie na zmeny povolení

---

404 Nenájdené

Zmyslenie: Prostredok neexistuje

Bežné príčiny:

• Neplatné ID prostriedku
• Prostredok bol vymazaný
• Prostredok patrí inej organizácii
• Preklep v URL koncového bodu

Príklady:

Agent nenájdený:

{
  "error": true,
  "statusCode": 404,
  "statusMessage": "Not Found",
  "message": "Agent not found"
}

Ako opraviť:

1. Overte, že ID prostriedku je správne
2. Skontrolujte, že prostredok nebol vymazaný
3. Potvrďte, že prostredok patrí vašej organizácii
4. Uveďte zoznam prostredkov na nájdenie správneho ID
5. Skontrolujte chyby v URL

---

429 Príliš mnoho požiadaviek

Zmyslenie: Prekročil limit frekvencie

Stav: V súčasnosti nie je vynútený, ale môže byť v budúcnosti

Ako opraviť:

1. Implementujte exponenciálny backoff
2. Znížte frekvenciu požiadaviek
3. Ukladajte do cache odozvy, keď je to možné
4. Kontaktujte podporu na vyššie limity

---

5xx Chyby servera

Tieto chyby naznačujú problémy na strane servera.

500 Interná chyba servera

Zmyslenie: Neočakávaná chyba servera

Bežné príčiny:

• Problémy s pripojením k databáze
• Selhanie závislosti služby
• Neošetrená výnimka
• Chyba konfigurácie

Príklad:

{
  "error": true,
  "statusCode": 500,
  "statusMessage": "Internal Server Error",
  "message": "An unexpected error occurred"
}

Ako opraviť:

1. Opakujte požiadavku (môže byť prechodný)
2. Skontrolujte stránku stavu API
3. Počkajte niekoľko minút a skúste znova
4. Kontaktujte podporu, ak je to pretrvávajúce
5. Skontrolujte známe problémy v dokumentácii

---

503 Služba nedostupná

Zmyslenie: Služba je dočasne nedostupná

Bežné príčiny:

• Plánovaná údržba
• Preťaženie systému
• Selhanie závislej služby

Príklad:

{
  "error": true,
  "statusCode": 503,
  "statusMessage": "Service Unavailable",
  "message": "Service temporarily unavailable. Please retry."
}

Ako opraviť:

1. Počkajte a opakujte s exponenciálnym backoffom
2. Skontrolujte stránku stavu na okna údržby
3. Kontaktujte podporu, ak je výpadok dlhý

---

Osvedčené postupy spracovania chýb

1. Vždy kontrolujte stavové kódy

const response = await fetch('https://us.teamday.ai/api/v1/agents', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
})

if (!response.ok) {
  const error = await response.json()
  console.error(`API Error ${error.statusCode}: ${error.message}`)
  // Spracujte chybu príslušne
}

const data = await response.json()

2. Spracujte špecifické prípady chýb

async function handleApiError(response) {
  const error = await response.json()

  switch (error.statusCode) {
    case 400:
      // Chyba validácie - opraviť požiadavku
      console.error('Invalid request:', error.message)
      break

    case 401:
      // Chyba autentifikácie - obnoviť token alebo znova sa autentifikovať
      console.error('Authentication failed:', error.message)
      await refreshToken()
      break

    case 404:
      // Nenájdené - prostredok neexistuje
      console.error('Resource not found:', error.message)
      break

    case 500:
      // Chyba servera - opakovať s backoffom
      console.error('Server error:', error.message)
      await retryWithBackoff()
      break

    default:
      console.error('Unexpected error:', error)
  }
}

3. Implementujte logiku opakovaných pokusov

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, options)

      if (response.ok) {
        return await response.json()
      }

      const error = await response.json()

      // Neopakovať chyby klienta (4xx)
      if (error.statusCode >= 400 && error.statusCode < 500) {
        throw new Error(error.message)
      }

      // Opakovať chyby servera (5xx) s exponenciálnym backoffom
      if (i < maxRetries - 1) {
        const delay = Math.pow(2, i) * 1000 // 1s, 2s, 4s
        console.log(`Retrying in ${delay}ms...`)
        await new Promise(resolve => setTimeout(resolve, delay))
        continue
      }

      throw new Error(error.message)

    } catch (err) {
      if (i === maxRetries - 1) throw err
    }
  }
}

---

Tabuľka referencie chýb

Rýchla referencia pre všetky chyby API:

Kód	Správa	Príčina	Riešenie
400	Chýbajúce povinné pole	Opustené povinné pole	Pridajte chýbajúce pole
400	Neplatný JSON	Malformovaný JSON	Overte syntax JSON
401	Vyžaduje sa hlavička Authorization	Chýbajúca hlavička	Pridajte hlavičku Authorization
401	Neplatný alebo expirovaný token	Zlý token	Vygenerujte nový token
403	Bez povolenia	Nedostatočné povolenia	Skontrolujte rolu používateľa
404	Agent nenájdený	Neplatné ID agenta	Overte, že agent existuje
429	Limit frekvencie prekročený	Príliš mnoho požiadaviek	Implementujte backoff
500	Interná chyba servera	Problém servera	Opakovať s backoffom
503	Služba nedostupná	Údržba/preťaženie	Počkajte a opakovajte

---

Kontaktovanie podpory

Email: support at teamday.ai

Zahrňte do požiadavky na podporu:

• Úplná chybová správa (úplný JSON)
• Podrobnosti požiadavky (koncový bod, metóda, hlavičky - BEZ tokenu)
• Kroky na reprodukciu
• Očakávané vs. skutočné správanie

---

Posledná aktualizácia: 9. december 2025