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

Chyby Magic Link

Endpoint GET /api/magiclink/validate vrací v odpovědi číselný kód chyby v poli errorCode a doprovodné textové vysvětlení v poli errorMessage. Pole errorCode je číslo (nikoli textový řetězec).

errorCode	Význam	Akce uživatele
1	Token nenalezen (TokenNotFound)	Požádejte o nový magic link
2	Platnost tokenu vypršela (TokenExpired)	Požádejte o nový magic link
3	Token již byl použit (TokenAlreadyUsed)	Požádejte o nový magic link
4	Uživatelský účet nenalezen (UserNotFound)	Kontaktujte podporu
5	Uživatelský účet deaktivován (UserNotActive)	Kontaktujte podporu
6	Účet uzamčen (UserLocked)	Počkejte nebo kontaktujte podporu
7	Neplatný formát tokenu (InvalidTokenFormat)	Požádejte o nový magic link
8	Neplatný tiket (InvalidTicket)	Požádejte o nový magic link

Příklad odpovědi při chybě:

{
  "valid": false,
  "userGuid": null,
  "email": null,
  "errorMessage": "The magic link has expired.",
  "errorCode": 2
}

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, nedostatečný scope
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 '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);
    }
  }
}