> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getqr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Chyby

> Formát chyb a chybové kódy, které vrací GetQR API.

> [!NOTE]
>
> GetQR API je v beta verzi a je dostupné pro vybrané pracovní prostory. Do obecného vydání se podrobnosti mohou změnit.

GetQR API používá standardní stavové kódy HTTP. Úspěšné požadavky vracejí `2xx`. Neúspěšné požadavky vracejí `4xx` nebo `5xx` s tělem JSON, které vysvětluje, co se pokazilo.

## Formát chyby

Každá chyba má stejný tvar: stálý kód, srozumitelnou zprávu a odkaz na popis daného kódu.

```json theme={null}
{
  "error": {
    "code": "unauthorized",
    "message": "Unauthorized: Invalid API key.",
    "doc_url": "https://getqr.com/account/api-docs#error-unauthorized"
  }
}
```

**error.code** `string` *required*

Stálý, strojově čitelný chybový kód. Ve svém kódu se řiďte jím, ne zprávou. Viz [Chybové kódy](#chybové-kódy).

**error.message** `string` *required*

Srozumitelný popis problému. Jeho znění se může změnit.

**error.doc\_url** `string` *required*

Odkaz na popis chybového kódu v dokumentaci API ve vašem účtu GetQR.

## Chybové kódy

| Kód | Stav HTTP | Kdy nastává |
| - | - | - |
| `bad_request` | 400 | Požadavek je chybně sestavený: tělo není platný JSON, hlavičce `Authorization` chybí prefix `Bearer `, nebo akce není v aktuálním stavu zdroje povolena (například zrušení dokončeného hromadného vytváření). |
| `unauthorized` | 401 | API klíč chybí nebo je neplatný, například proto, že byl přegenerován. |
| `forbidden` | 403 | Předplatné vlastníka pracovního prostoru není aktivní, nebo vaše role v pracovním prostoru tuto akci nepovoluje. |
| `exceeded_limit` | 403 | Dosáhli jste limitu tarifu. V tarifu Single QR jde o vytvoření nebo duplikaci QR kódu, když už pracovní prostor jeden má, nebo o spuštění hromadného vytváření. |
| `not_found` | 404 | Zdroj neexistuje nebo nepatří do vašeho pracovního prostoru, endpoint neexistuje, nebo API není pro váš pracovní prostor zapnuté. |
| `method_not_allowed` | 405 | Endpoint existuje, ale tuto metodu HTTP nepřijímá. Hlavička `Allow` uvádí metody, které přijímá. |
| `conflict` | 409 | Požadavek je v rozporu s existujícími daty: slug krátkého odkazu je obsazený, požadavek se stejným `Idempotency-Key` ještě probíhá, plán se překrývá s existujícím, nebo hromadný archiv ještě není připravený. |
| `invite_pending` | 409 | Byli jste do pracovního prostoru pozváni, ale ještě jste se nepřipojili. Požadavky s API klíčem tento kód nevracejí: pracovní prostor klíče je vždy ten, do kterého patříte. |
| `invite_expired` | 410 | Vaše pozvánka do pracovního prostoru vypršela. Požadavky s API klíčem tento kód ze stejného důvodu nevracejí. |
| `unprocessable_entity` | 422 | Tělo nebo parametry dotazu neprošly validací. Zpráva uvádí pole a co je na něm špatně. Viz [Chyby validace](#chyby-validace). |
| `rate_limit_exceeded` | 429 | API klíč vyčerpal požadavky v aktuálním okně. Viz [Limity požadavků](https://docs.getqr.com/cs/api/rate-limits.md). |
| `internal_server_error` | 500 | Na naší straně se něco pokazilo. Zkuste to později znovu, a pokud potíže trvají, kontaktujte podporu. |

## Chyby validace

Když tělo nebo parametry dotazu neprojdou validací, API odpoví `422`. Zpráva popisuje první neplatné pole ve tvaru `<issue>: <field>: <details>`:

```json theme={null}
{
  "error": {
    "code": "unprocessable_entity",
    "message": "too_big: pageSize: Max page size is 100.",
    "doc_url": "https://getqr.com/account/api-docs#error-unprocessable_entity"
  }
}
```

Vnořená pole se zapisují tečkovou notací, například `link.url`.

## Zpracování chyb

* Rozhodujte se podle `error.code`, ne podle `error.message`.
* Chyby `4xx` neopakujte beze změny: nejdřív požadavek opravte. Výjimkou je `409` u požadavku, který ještě probíhá, a `429`.
* Při `429` počkejte tolik sekund, kolik uvádí hlavička `Retry-After`. Viz [Limity požadavků](https://docs.getqr.com/cs/api/rate-limits.md#při-překročení-limitu).
* Chyby `5xx` opakujte s exponenciálním odstupem.

## Časté problémy

> [accordion] Každý požadavek vrací 404 "This endpoint is not available."
>
> API je v beta verzi a pro váš pracovní prostor zatím není zapnuté.

> [accordion] 404 "This endpoint does not exist."
>
> Cesta je špatně. Porovnejte ji se stránkami endpointů a ověřte, že začíná na `/api/v1/`.

> [accordion] 403 "Access denied: This account does not have an active subscription."
>
> Předplatné vlastníka pracovního prostoru skončilo. API klíč začne znovu fungovat, jakmile si vlastník předplatné obnoví.

> [accordion] 403 "API access is not available for this role."
>
> Vaše role v pracovním prostoru je čtenář. API mohou používat jen vlastník pracovního prostoru a editoři.

## Co dál

> [card] [Limity požadavků](https://docs.getqr.com/cs/api/rate-limits.md)

> [card] [Ověřování](https://docs.getqr.com/cs/api/authentication.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.