Přehled chyb

Standardní OAuth 2.0 chyby

Tyto chyby jsou vráceny prostřednictvím query parametrů redirect URL nebo v odpovědích token endpointu.

Kód chyby	HTTP Status	Popis	Běžná příčina
invalid_request	400	Požadavku chybí povinný parametr	Chybí client_id, redirect_uri, atd.
invalid_client	401	Autentizace klienta selhala	Špatný client_id nebo client_secret
invalid_grant	400	Grant je neplatný	Kód vypršel, již použit nebo špatné redirect_uri
invalid_scope	400	Požadovaný scope není povolen	Scope není registrován pro klienta
unauthorized_client	401	Klient není autorizován pro grant type	Flow není povoleno pro klienta
unsupported_grant_type	400	Grant type není podporován	Použití nepodporovaného flow
access_denied	403	Uživatel odmítl autorizaci	Uživatel klikl na "Zamítnout"
consent_required	400	Vyžadován souhlas ale prompt=none	Použijte interaktivní flow
login_required	400	Uživatel není přihlášen ale prompt=none	Použijte interaktivní flow
server_error	500	Server narazil na chybu	Kontaktujte podporu
temporarily_unavailable	503	Server dočasně nedostupný	Zkuste později

Chyby validace tokenu

Chyba	HTTP Status	Popis	Řešení
invalid_token	401	Token je neplatný nebo vypršel	Obnovte nebo se znovu autentizujte
insufficient_scope	403	Token nemá požadovaný scope	Požádejte o další scopes

Vlastní chyby

Vyžadováno MFA

{
  "error": "mfa_required",
  "error_description": "Two-factor authentication required."
}

HTTP Status: 403 Forbidden

Kdy: Uživatel má povolené 2FA a používá Resource Owner Password Grant (legacy flow)

Řešení: Dokončete 2FA ověření před opakováním. Viz dokumentace 2FA.

tip

Při použití Authorization Code Flow (doporučeno) se tato chyba nevyskytuje - 2FA je automaticky součástí přihlašovací stránky.

Chyby Magic Link

Kód chyby	Popis	Akce uživatele
TokenNotFound	Token neexistuje	Požádejte o nový magic link
TokenExpired	Platnost tokenu překročena (15 min)	Požádejte o nový magic link
TokenAlreadyUsed	Token byl spotřebován	Požádejte o nový magic link
UserNotFound	Uživatelský účet nenalezen	Kontaktujte podporu
UserNotActive	Uživatelský účet deaktivován	Kontaktujte podporu
UserLocked	Účet uzamčen	Počkejte nebo kontaktujte podporu
InvalidTokenFormat	Token je poškozený	Požádejte o nový magic link

Přehled HTTP status kódů

Status kód	Význam	Běžné scénáře
200	Úspěch	Úspěšný požadavek
302	Redirect	OAuth přesměrování
400	Bad Request	Neplatné parametry
401	Unauthorized	Neplatné přihlašovací údaje nebo token
403	Forbidden	Přístup odepřen, vyžadováno MFA
404	Not Found	Zdroj neexistuje
429	Too Many Requests	Překročen rate limit
500	Server Error	Interní chyba
503	Service Unavailable	Dočasná nedostupnost

Formáty chybových odpovědí

Authorization endpoint (přes redirect)

https://myapp.com/callback?error=access_denied&error_description=User%20denied%20access&state=xyz

Token endpoint (JSON)

{
  "error": "invalid_grant",
  "error_description": "The authorization code has expired."
}

Zpracování chyb

// Příklad zpracování chyb
async function handleTokenResponse(response) {
  if (!response.ok) {
    const error = await response.json();

    switch (error.error) {
      case 'invalid_grant':
        // Kód vypršel nebo neplatný - restartovat flow
        redirectToLogin();
        break;
      case 'mfa_required':
        // Zobrazit 2FA ověřovací UI
        showTwoFactorPrompt();
        break;
      case 'invalid_client':
        // Chyba konfigurace - zkontrolovat přihlašovací údaje
        console.error('Neplatné přihlašovací údaje klienta');
        break;
      default:
        console.error('OAuth chyba:', error.error_description);
    }
  }
}