Reference chyb API

Tato příručka dokumentuje všechny chybové kódy, formáty odpovědí a kroky pro odstraňování problémů TeamDay API.

---

Formát chybové odpovědi

Všechny chyby API mají konzistentní strukturu JSON:

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

Pole:

• error (boolean) - Vždy true pro chybové odpovědi
• statusCode (number) - HTTP stavový kód
• statusMessage (string) - Lidsky čitelný status
• message (string) - Podrobné vysvětlení chyby

---

Stavové kódy HTTP

2xx Úspěch

Toto nejsou chyby, ale úspěšné odpovědi:

200 OK

Význam: Požadavek se zdařil

Používáno:

• GET požadavky (seznam, získání detailů)
• PATCH požadavky (aktualizace)
• DELETE požadavky (měkké smazání)
• POST požadavky (zrušení spuštění)

Příklad:

{
  "id": "agent_abc123",
  "name": "Výzkumný asistent",
  "...": "..."
}

201 Vytvořeno

Význam: Zdroj úspěšně vytvořen

Používáno:

• POST požadavky (vytvoření agenta, úkolu)

Příklad:

{
  "id": "agent_abc123",
  "name": "Výzkumný asistent",
  "createdAt": "2025-12-09T10:00:00Z",
  "...": "..."
}

---

4xx Chyby klienta

Tyto chyby naznačují problémy s požadavkem.

400 Chybný požadavek

Význam: Neplatné parametry požadavku nebo chybějící povinná pole

Běžné příčiny:

• Chybějící povinná pole
• Neplatné hodnoty polí
• Poškozený JSON
• Neplatné parametry dotazu

Příklady:

Chybějící povinné pole:

{
  "error": true,
  "statusCode": 400,
  "statusMessage": "Bad Request",
  "message": "Chybí povinné pole: name"
}

Neplatná hodnota visibility:

{
  "error": true,
  "statusCode": 400,
  "statusMessage": "Bad Request",
  "message": "Neplatná hodnota visibility. Musí být: private, organization nebo public"
}

Neplatný status:

{
  "error": true,
  "statusCode": 400,
  "statusMessage": "Bad Request",
  "message": "Neplatný status. Musí být: pending, in_progress, completed, cancelled"
}

Poškozený JSON:

{
  "error": true,
  "statusCode": 400,
  "statusMessage": "Bad Request",
  "message": "Neplatný JSON v těle požadavku"
}

Jak opravit:

1. Zkontrolujte, zda tělo požadavku odpovídá dokumentaci API
2. Ověřte, že jsou přítomna všechna povinná pole
3. Ověřte, že hodnoty polí jsou platné (enums, typy)
4. Testujte syntaxi JSON validátorem

---

401 Neautorizováno

Význam: Ověření selhalo nebo chybí

Běžné příčiny:

• Chybějící Authorization záhlaví
• Neplatný token
• Vypršelý token
• Nesprávný formát tokenu

Příklady:

Chybějící záhlaví:

{
  "error": true,
  "statusCode": 401,
  "statusMessage": "Unauthorized",
  "message": "Authorization header required"
}

Neplatný token:

{
  "error": true,
  "statusCode": 401,
  "statusMessage": "Unauthorized",
  "message": "Invalid or expired token"
}

Vypršelý token:

{
  "error": true,
  "statusCode": 401,
  "statusMessage": "Unauthorized",
  "message": "Token expired"
}

Chybný formát:

{
  "error": true,
  "statusCode": 401,
  "statusMessage": "Unauthorized",
  "message": "Token must start with 'td_'"
}

Jak opravit:

1. Zkontrolujte, že je přítomno Authorization záhlaví
2. Ověřte formát záhlaví: Authorization: Bearer td_xxxxx...
3. Potvrďte, že token nevypršel v Settings → API Access
4. V případě potřeby vygenerujte nový token
5. Zkontrolujte, že je token zkopírován správně (bez extra mezer)

---

403 Zakázáno

Význam: Ověřeno, ale není autorizováno pro tuto akci

Běžné příčiny:

• Uživatel nemá požadovaná oprávnění
• Přístup do organizace odvolán
• Zdroj patří jiné organizaci

Příklad:

{
  "error": true,
  "statusCode": 403,
  "statusMessage": "Forbidden",
  "message": "Nemáte oprávnění pro přístup k tomuto zdroji"
}

Jak opravit:

1. Ověřte, že uživatel má správnou roli/oprávnění
2. Zkontrolujte, že uživatel stále patří do organizace
3. Potvrďte, že zdroj patří vaší organizaci
4. Kontaktujte správce organizace pro změny oprávnění

---

404 Nenalezeno

Význam: Zdroj neexistuje

Běžné příčiny:

• Neplatné ID zdroje
• Zdroj byl smazán
• Zdroj patří jiné organizaci
• Překlep v URL endpointu

Příklady:

Agent nenalezen:

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

Spuštění nenalezeno:

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

Úkol nenalezen:

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

Jak opravit:

1. Ověřte, že ID zdroje je správné
2. Zkontrolujte, že zdroj nebyl smazán
3. Potvrďte, že zdroj patří vaší organizaci
4. Seznamem zdrojů najděte správné ID
5. Zkontrolujte překlepy v URL

---

429 Příliš mnoho požadavků

Význam: Překročeno omezení sazby

Status: Zatím není vynuceno, ale může být v budoucnosti

Příklad:

{
  "error": true,
  "statusCode": 429,
  "statusMessage": "Too Many Requests",
  "message": "Omezení sazby překročeno. Opakujte po 60 sekundách."
}

Jak opravit:

1. Implementujte exponenciální zpoždění
2. Snižte frekvenci požadavků
3. Ukládat do mezipaměti odpovědi, je-li možné
4. Kontaktujte podporu pro vyšší limity

---

5xx Chyby serveru

Tyto chyby naznačují problémy na straně serveru.

500 Interní chyba serveru

Význam: Neočekávaná chyba serveru

Běžné příčiny:

• Problémy s připojením k databázi
• Selhání závislostí služby
• Neošetřená výjimka
• Chyba v konfiguraci

Příklad:

{
  "error": true,
  "statusCode": 500,
  "statusMessage": "Internal Server Error",
  "message": "Došlo k neočekávané chybě"
}

Známé problémy:

Spuštění agenta nefunguje:

{
  "error": true,
  "statusCode": 500,
  "statusMessage": "Internal Server Error",
  "message": "Spuštění chatu selhalo"
}

Příčina: Problém s interním endpointem /api/claude-code/chat

Dočasné řešení: Použijte webové rozhraní pro spuštění agenta

Jak opravit:

1. Opakujte požadavek (může být přechodný)
2. Zkontrolujte stránku stavu API
3. Počkejte několik minut a opakujte
4. Kontaktujte podporu, pokud přetrvává
5. Zkontrolujte známé problémy v dokumentaci

---

503 Služba není dostupná

Význam: Služba je dočasně nedostupná

Běžné příčiny:

• Plánovaná údržba
• Přetížení systému
• Selhání závislé služby

Příklad:

{
  "error": true,
  "statusCode": 503,
  "statusMessage": "Service Unavailable",
  "message": "Služba je dočasně nedostupná. Prosím opakujte."
}

Jak opravit:

1. Počkejte a opakujte s exponenciálním zpožděním
2. Zkontrolujte stránku stavu pro okna údržby
3. Kontaktujte podporu, pokud výpadek přetrvává

---

Osvědčené postupy zpracování chyb

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}`)
  // Zpracujte chybu vhodně
}

const data = await response.json()

2. Zpracujte konkrétní případy chyb

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

  switch (error.statusCode) {
    case 400:
      // Chyba ověření - opravte požadavek
      console.error('Neplatný požadavek:', error.message)
      break

    case 401:
      // Chyba ověření - obnovte token nebo znovu ověřte
      console.error('Ověření selhalo:', error.message)
      await refreshToken()
      break

    case 404:
      // Nenalezeno - zdroj neexistuje
      console.error('Zdroj nenalezen:', error.message)
      break

    case 500:
      // Chyba serveru - opakujte se zpožděním
      console.error('Chyba serveru:', error.message)
      await retryWithBackoff()
      break

    default:
      console.error('Neočekávaná chyba:', error)
  }
}

3. Implementujte logiku opakování

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()

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

      // Opakujte chyby serveru (5xx) s exponenciálním zpožděním
      if (i < maxRetries - 1) {
        const delay = Math.pow(2, i) * 1000 // 1s, 2s, 4s
        console.log(`Opakování za ${delay}ms...`)
        await new Promise(resolve => setTimeout(resolve, delay))
        continue
      }

      throw new Error(error.message)

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

4. Zaznamenávejte chyby vhodně

async function makeApiRequest(endpoint, options) {
  try {
    const response = await fetch(endpoint, options)

    if (!response.ok) {
      const error = await response.json()

      // Zaznamenávejte detaily chyby (ale ne citlivá data)
      console.error('API Error:', {
        endpoint,
        statusCode: error.statusCode,
        message: error.message,
        timestamp: new Date().toISOString()
        // Nezaznamenávejte: tokeny, hesla, PII
      })

      throw error
    }

    return await response.json()

  } catch (err) {
    // Zaznamenávejte výjimku
    console.error('Požadavek selhal:', {
      endpoint,
      error: err.message,
      timestamp: new Date().toISOString()
    })

    throw err
  }
}

5. Poskytujte uživatelsky přívětivé zprávy

function getUserFriendlyError(apiError) {
  const messages = {
    400: 'Neplatný požadavek. Prosím zkontrolujte váš vstup.',
    401: 'Ověření selhalo. Prosím přihlaste se znovu.',
    403: 'Nemáte oprávnění k provedení této akce.',
    404: 'Požadovaný zdroj nebyl nalezen.',
    429: 'Příliš mnoho požadavků. Prosím zkuste později.',
    500: 'Chyba serveru. Prosím zkuste znovu.',
    503: 'Služba je dočasně nedostupná. Prosím zkuste brzy.'
  }

  return messages[apiError.statusCode] || 'Došlo k neočekávané chybě.'
}

// Použití
try {
  const data = await createAgent(agentData)
} catch (err) {
  const userMessage = getUserFriendlyError(err)
  showErrorToUser(userMessage)
}

---

Běžné scénáře chyb

Scénář 1: Token vypršel

Chyba:

{
  "statusCode": 401,
  "message": "Token expired"
}

Řešení:

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

    if (response.status === 401) {
      console.log('Token vypršel, generování nového...')
      // Přesměrujte na dashboard pro vygenerování nového tokenu
      window.location.href = 'https://us.teamday.ai/settings/api'
    }

  } catch (err) {
    console.error('Ověření tokenu selhalo:', err)
  }
}

---

Scénář 2: Chybějící povinné pole

Chyba:

{
  "statusCode": 400,
  "message": "Missing required field: name"
}

Řešení:

async function createAgent(agentData) {
  // Ověřte povinná pole před voláním API
  const required = ['name', 'systemPrompt']

  for (const field of required) {
    if (!agentData[field]) {
      throw new Error(`Chybí povinné pole: ${field}`)
    }
  }

  // Zavolajte API
  const response = await fetch('https://us.teamday.ai/api/v1/agents', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(agentData)
  })

  if (!response.ok) {
    const error = await response.json()
    throw error
  }

  return await response.json()
}

---

Scénář 3: Agent nenalezen

Chyba:

{
  "statusCode": 404,
  "message": "Agent not found"
}

Řešení:

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

    if (response.status === 404) {
      console.log(`Agent ${agentId} nenalezen. Může být smazán.`)
      return null
    }

    if (!response.ok) {
      throw await response.json()
    }

    return await response.json()

  } catch (err) {
    console.error('Načtení agenta selhalo:', err)
    return null
  }
}

---

Tabulka reference chyb

Rychlý přehled všech chyb API:

Kód	Zpráva	Příčina	Řešení
400	Chybí povinné pole	Vynechané povinné pole	Přidejte chybějící pole
400	Neplatný JSON	Poškozený JSON	Ověřte syntaxi JSON
400	Neplatná viditelnost	Chybná hodnota enum	Použijte: private, organization, public
401	Záhlaví autorizace je vyžadováno	Chybějící záhlaví	Přidejte záhlaví autorizace
401	Neplatný nebo vypršelý token	Špatný token	Vygenerujte nový token
403	Bez oprávnění	Nedostatečná oprávnění	Zkontrolujte roli uživatele
404	Agent nenalezen	Neplatné ID agenta	Ověřte existenci agenta
429	Omezení sazby překročeno	Příliš mnoho požadavků	Implementujte zpoždění
500	Interní chyba serveru	Problém serveru	Opakujte se zpožděním
503	Služba není dostupná	Údržba/přetížení	Čekejte a opakujte

---

Tipy pro ladění

1. Zkontrolujte záhlaví požadavku

# Použijte curl -v pro podrobný výstup
curl -v https://us.teamday.ai/api/v1/agents \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

# Zkontrolujte odesílaná záhlaví

2. Ověřte JSON

# Použijte jq k ověření JSON
echo '{
  "name": "Test Agent",
  "systemPrompt": "Jste užitečný"
}' | jq .

# Měl by vygenerovat formátovaný JSON, pokud je platný

3. Testujte ověřování

# Rychlý test ověření
curl https://us.teamday.ai/api/v1/agents \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

# Měl by vrátit 200 se seznamem agentů (nebo prázdné pole)

---

Potřebujete pomoc?

Zkontrolujte dokumentaci:

• API Overview - Obecné informace o API
• Ověřování - Nastavení tokenu
• API Agentů - Endpointy agentů
• API Spuštění - Endpointy spuštění

Kontaktujte podporu:

E-mail: support at teamday.ai

Zahrňte do žádosti o podporu:

• Chybová zpráva (úplný JSON)
• Detaily požadavku (endpoint, metoda, záhlaví - BEZ tokenu)
• Kroky k reprodukci
• Očekávané vs. skutečné chování

Zdroje komunity:

Discord: Připojit se ke komunitě

GitHub Issues: Hlásit chyby

---

Poslední aktualizace: 9. prosince 2025