Chybové kódy

Používame štandardné HTTP kódy odpovedí na indikáciu úspechu alebo zlyhania API požiadaviek. Kódy v rozsahu 2xx označujú úspešné požiadavky, kódy 4xx signalizujú chyby spôsobené klientskou stranou (napr. chýbajúce alebo neplatné parametre, prekročenie limitov) a 5xx indikujú problémy na strane servera.

Stavové kódy HTTP

  • Name
    200 - OK
    Type
    Description

    Štandardná odpoveď pre úspešnú HTTP požiadavku.

  • Name
    400 - Bad Request
    Type
    Description

    Požiadavka nemôže byť spracovaná, pretože obsahuje syntaktické chyby.

  • Name
    401 - Unauthorized
    Type
    Description

    API kľúč je neplatný alebo chýba.

  • Name
    402 - Request Failed
    Type
    Description

    Požiadavka zlyhala z iných dôvodov.

  • Name
    404 - Not Found
    Type
    Description
    Požadovaná položka nebola nájdená.
  • Name
    5XX - Server Errors
    Type
    Description

    Došlo k neočakávanému problému na strane servera.

Štruktúra a kategórie chýb

Atribúty chybovej odpovede

  • Name
    type
    Type
    Description

    Typ chyby, napr. invalid_request alebo api_error.

  • Name
    message
    Type
    Description

    Správa obsahujúca ďalšie podrobnosti o chybe.

  • Name
    code
    Type
    Description

    Kódové označenie chyby.

  • Name
    param
    Type
    Description

    Parameter, na ktorý sa chyba vzťahuje, ak je chyba špecifická.

Typy chýb

  • Name
    invalid_request
    Type
    Description

    Vzniká, ak požiadavka obsahuje neplatné alebo nesprávne parametre. Tento typ chyby pokrýva aj neočakávané problémy, ako sú dočasné problémy so serverom.

  • Name
    api_error
    Type
    Description

    Vzniká pri neočakávaných chybách na strane API. Detailná správa obsahuje ďalšie informácie o chybe.

Kódy chýb

  • Name
    invalid_parameter
    Type
    Description

    Vzniká, ak parameter obsahuje neplatnú hodnotu.

  • Name
    unexpected_parameter
    Type
    Description

    Vzniká, ak je použitý neexistujúci parameter.

  • Name
    over_query_limit
    Type
    Description

    Indikuje prekročenie mesačného limitu.

  • Name
    rate_limit
    Type
    Description

    Vzniká pri príliš častom odosielaní požiadaviek v krátkom časovom intervale.

  • Name
    missing
    Type
    Description

    Indikuje, že požadovaný detail (napr. miesto alebo právnická osoba) neexistuje.

  • Name
    restricted
    Type
    Description

    Vzniká, ak API kľúč má obmedzený prístup (napr. pre konkrétnu doménu alebo IP adresu) alebo ak vyhľadávate v oblasti, ku ktorej nemáte oprávnenie.

Chybová odpoveď

{
    "error": {
        "message": "API key is required.",
        "type": "invalid_request",
        "code": "missing_key",
        "param": "api_key"
    }
}

Odchytávanie chýb

Naše API knižnice môžu vyvolať výnimky z rôznych dôvodov, ako sú prekročenie limitov, neplatné parametre, chyby autentifikácie alebo problémy so sieťou. Odporúčame implementovať robustný systém odchytávania výnimiek, aby bolo možné elegantne zvládnuť prípadné chyby.

Príklad volania API

try {
  // ...
} catch (\Swiftyper\Error\InvalidRequest $e) {
  // V prípade zadania neplatných parametrov
  $body = $e->getJsonBody();
  $err  = $body['error'];

  print('Stavový kód:' . $e->getHttpStatus() . "\n");
  print('Typ chyby:' . $err['type'] . "'\n");
  print('Kód chyby:' . $err['code'] . "'\n");
  print('Parameter:' . $err['param'] . "\n");
  print('Popis chyby:' . $err['message'] . "\n");
} catch (\Swiftyper\Error\Authentication $e) {
  // V prípade neúspešnej autentifikácie
} catch (\Swiftyper\Error\Quota $e) {
  // V prípade presiahnutia mesačného limitu
} catch (\Swiftyper\Error\ApiConnection $e) {
  // V prípade zlyhania sieťovej komunikácie
} catch (Exception $e) {
  // V prípade inej chyby nesúvisiacej so službou Swiftyper
}