# Chyby

> Jak API Emailitu hlásí chyby. Formáty těla odpovědi, stavové kódy HTTP a jejich význam a řešení nejčastějších chybových zpráv.

API Emailitu pomocí stavových kódů HTTP sděluje, jestli požadavek uspěl. Kódy v rozsahu `2xx` znamenají úspěch, kódy `4xx` znamenají, že je potřeba něco v požadavku změnit, a kódy `5xx` znamenají, že se něco pokazilo na naší straně. Tato stránka popisuje těla chybových odpovědí, všechny stavové kódy, které API vrací, a řešení nejčastějších chyb.

## Formáty chybových odpovědí

Tělo každé chyby je objekt JSON s polem `error`. Přesný tvar závisí na tom, kde požadavek selhal. Ošetření chyb napište tak, aby četlo `error`, pak `message`, pokud je přítomné, a pak případná další pole, která endpoint dokumentuje.

### Chyby požadavku

Selhání autentizace, chyby oprávnění, chybný JSON a další chyby, které vzniknou dřív, než se endpoint spustí, používají standardní formát chyb HTTP:

```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "API key required"
}
```

| Pole | Popis |
| --- | --- |
| `statusCode` | Stavový kód HTTP. |
| `error` | Textový popis stavu HTTP, například `Unauthorized` nebo `Forbidden`. |
| `message` | Co se pokazilo, srozumitelnými slovy. |

### Chyby validace

Když má parametr dotazu nebo pole v těle požadavku špatný typ, chybí, nebo je mimo povolený rozsah, API požadavek ještě před spuštěním odmítne s `400` a jednotlivé problémy uvede v poli `details`:

```json
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Validation error",
  "details": [
    {
      "instancePath": "/limit",
      "schemaPath": "#/properties/limit/maximum",
      "keyword": "maximum",
      "params": { "comparison": "<=", "limit": 100 },
      "message": "must be <= 100"
    }
  ]
}
```

`instancePath` ukazuje na pole (`/limit`, `/to`, `/attachments/0/filename`) a `message` popisuje pravidlo, které porušilo. U několika endpointů, například [Odeslání e-mailu](/cs/docs/api-reference/emails/send/), tyto chyby vracejí jen `{"error": "Bad Request"}`.

### Chyby zdrojů

Chyby, které vyvolá samotný endpoint, například chybějící objekt nebo duplicitní název, vracejí `error` a často i `message`:

```json
{
  "error": "Email not found",
  "message": "Email with ID 'em_4KYof1ZzXndZE2VPi0DgULiekG8' not found in your workspace"
}
```

Některé chyby přidávají pole, která vám pomohou situaci vyřešit:

| Pole | Vrací se s | Obsahuje |
| --- | --- | --- |
| `existing` | `409`, když vytvoříte duplicitní doménu, API klíč, seznam kontaktů, kontakt nebo odběratele | Objekt, který už existuje, takže ho můžete použít místo nového. |
| `usage` | `422` při dosažení limitu tarifu | `used`, `limit` a u seznamů kontaktů `plan`. |
| `required_plan` | `403` s `error: "plan_required"` | Nejnižší tarif, který funkci obsahuje, například `pro`. |
| `code` | Některé chyby `403` a `422` | Stálý strojově čitelný kód, například `unverified_workspace_recipient` nebo `events_offset_too_large`. |
| `missing` | `404` z [hromadné úpravy kontaktů](/cs/docs/api-reference/contacts/bulk/) | ID kontaktů, které se nenašly. |

### Chyby validace při odesílání

[Odeslání e-mailu](/cs/docs/api-reference/emails/send/) a [Přeposlání e-mailu](/cs/docs/api-reference/emails/forward/) kontrolují celou zprávu najednou a všechny problémy vracejí v poli `validation_errors`:

```json
{
  "error": "Validation failed",
  "validation_errors": [
    "Missing required field: subject",
    "Invalid to email address at index 1: ada@example"
  ]
}
```

### Chyby polí

Šablony, kampaně a automatizace vracejí problémy s validací seskupené podle polí:

```json
{
  "message": "Validation failed",
  "errors": {
    "alias": ["Alias must contain only lowercase letters (a-z), numbers (0-9), underscores (_), and hyphens (-)"]
  }
}
```

### Chyby limitů rychlosti

Odpovědi `429` z endpointů pro odesílání obsahují limit, na který jste narazili, a jak dlouho máte počkat. Viz [Limity rychlosti](/cs/docs/api-reference/rate-limits/).

```json
{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Maximum 2 messages per second allowed.",
  "limit": 2,
  "current": 2,
  "retry_after": 1
}
```

## Stavové kódy HTTP

| Kód | Význam | Typické příčiny v API Emailitu |
| --- | --- | --- |
| `200` | OK | Požadavek uspěl. Odeslání, úpravy, smazání a čtení vracejí `200`. |
| `201` | Created | Byla vytvořena doména, API klíč, seznam kontaktů, odběratel, kontakt, šablona, webhook nebo jiný objekt. |
| `202` | Accepted | Nahraný DMARC report byl přijat ke zpracování. |
| `204` | No Content | Byl smazán formulář. Odpověď nemá tělo. |
| `400` | Bad Request | Neplatný JSON, chybějící povinné pole, hodnota špatného typu nebo mimo rozsah, neplatná hlavička `Idempotency-Key` nebo žádná pole k úpravě. |
| `401` | Unauthorized | API klíč chybí, je neplatný, smazaný nebo znovu vygenerovaný, nebo vypršel token OAuth. Viz [Autentizace](/cs/docs/api-reference/authentication/#authentication-errors). |
| `402` | Payment Required | Workspace nemá dost kreditů na odeslání, opakované odeslání nebo ověření. |
| `403` | Forbidden | Oprávnění klíče endpoint nepovoluje, klíč omezený na doménu odesílal z jiné domény, workspace je zablokovaný nebo ještě není ověřený, odesílací doména je pozastavená, nebo funkce vyžaduje vyšší tarif. |
| `404` | Not Found | Objekt v tomto workspace neexistuje, nebo alias šablony nemá publikovanou verzi. |
| `409` | Conflict | Objekt se stejným názvem nebo e-mailem už existuje, nebo ještě probíhá požadavek se stejnou hlavičkou `Idempotency-Key`. |
| `413` | Payload Too Large | Sestavený e-mail je větší než 40 MB, nebo nahrávaný DMARC report je větší než 10 MB. |
| `422` | Unprocessable Entity | Požadavek je platný, ale teď ho nelze provést: doména v `from` není ověřená, přílohu se nepodařilo stáhnout, stav e-mailu nedovoluje zrušení nebo opakované odeslání, jeho obsah už byl smazán, nebo byl dosažen limit tarifu. |
| `429` | Too Many Requests | Workspace dosáhl limitu odesílání za sekundu nebo denního limitu, případně hodinového limitu přeposílání. |
| `500` | Internal Server Error | Něco selhalo na naší straně. Zopakujte požadavek s rostoucím odstupem, a pokud problém trvá, napište podpoře. |
| `503` | Service Unavailable | Dočasný výpadek služby, na které API závisí, například úložiště idempotenčních klíčů nebo autentizační databáze. Zopakujte požadavek s rostoucím odstupem. |

## Časté chyby a jejich řešení

| Stav | `error` | Příčina | Řešení |
| --- | --- | --- | --- |
| `400` | `Validation failed` | Požadavku na odeslání chybí `from`, `to`, `subject` nebo obsah, nebo obsahuje neplatnou adresu či přílohu. | Opravte každou položku uvedenou ve `validation_errors`. |
| `400` | `Invalid JSON in request body` (v `message`) | Tělo není platný JSON. | Zkontrolujte uvozovky a koncové čárky a pošlete `Content-Type: application/json`. |
| `400` | `Invalid Idempotency-Key` | Klíč je delší než 256 znaků, nebo obsahuje jiné znaky než písmena, číslice, `-` a `_`. | Použijte UUID nebo podobnou bezpečnou hodnotu. |
| `402` | `Insufficient credits` | Došly kredity. Každý příjemce stojí jeden kredit. | Kupte kredity, nebo zapněte [automatické dobíjení](/cs/docs/billing/auto-refill/). |
| `403` | `Workspace not verified` | Workspace je v režimu sandbox a některý příjemce není členem workspace. | Požádejte o [produkční přístup](/cs/docs/workspaces/production-access/). |
| `403` | `Domain paused` | Odesílání z této domény je pozastavené kvůli její [kondici odesílání](/cs/docs/deliverability/sending-health/). | Vyřešte problém s nedoručením nebo stížnostmi a pak napište podpoře. |
| `403` | `Domain not authorized` | API klíč je omezený na jinou odesílací doménu. | Odesílejte z domény klíče, nebo použijte jiný klíč. |
| `403` | `plan_required` | Funkce, například DMARC reporty nebo filtry webhooků, není ve vašem tarifu. | Přejděte na tarif uvedený v `required_plan`. |
| `403` | `mjml_alpha` | Požadavek vytváří nebo mění MJML, nebo volá endpoint MJML. MJML je v alfaverzi a otevřené jen týmu Emailitu. | Použijte jiný editor nebo typ obsahu. Viz [Editory a API pro MJML](/cs/docs/templates/mjml/#who-can-use-mjml). |
| `404` | `Template not found` | ID šablony neexistuje, nebo alias nemá publikovanou verzi. | [Publikujte](/cs/docs/api-reference/templates/publish/) verzi šablony. |
| `409` | `… already exists` | Vytvořili jste objekt s názvem nebo e-mailem, který už je obsazený. | Použijte objekt z `existing`, nebo zvolte jiný název. |
| `409` | `Idempotency key in progress` | Jiný požadavek se stejným klíčem ještě neskončil. | Chvíli počkejte a požadavek zopakujte se stejným klíčem. |
| `413` | `Message too large` | E-mail včetně příloh má víc než 40 MB. | Velké soubory posílejte jako odkazy místo příloh. |
| `422` | `Domain not verified` | Adresa v `from` není na ověřené odesílací doméně tohoto workspace. | [Ověřte doménu](/cs/docs/domains/verification/), nebo změňte `from`. |
| `422` | `Attachment error` | Přílohu z `url` se nepodařilo stáhnout do 30 sekund, není dostupná, nebo je větší než 25 MB. | Zkontrolujte, že je URL veřejná a soubor dost malý, nebo místo toho pošlete `content`. |
| `422` | `Cannot cancel email`, `Cannot retry email`, `Cannot update email` | Stav e-mailu akci nedovoluje, do naplánovaného času zbývají méně než 3 minuty, nebo byl obsah smazán. | Zkontrolujte `status` e-mailu. Pravidla najdete u jednotlivých endpointů. |
| `422` | `Page is too deep` | Ve [výpisu událostí](/cs/docs/api-reference/events/list/) jste stránkovali za offset 2 500. | Zužte výsledky filtry `type` nebo `created_at`. |
| `429` | `Rate limit exceeded`, `Daily limit exceeded` | Workspace dosáhl limitu odesílání. | Počkejte `retry_after` sekund. Viz [Limity rychlosti](/cs/docs/api-reference/rate-limits/). |

## Opakujte požadavky bezpečně

- Odpovědi `429`, `500` a `503` opakujte po prodlevě. Pokud je přítomná hlavička `retry-after`, řiďte se jí, jinak použijte exponenciálně rostoucí odstup. Ukázkový kód najdete na stránce [Limity rychlosti](/cs/docs/api-reference/rate-limits/#retry-with-backoff).
- Ostatní chyby `4xx` beze změny neopakujte. Selžou stejně, dokud požadavek neopravíte.
- Když opakujete odeslání po vypršení časového limitu nebo chybě `5xx`, použijte stejnou hlavičku [`Idempotency-Key`](/cs/docs/api-reference/idempotency/), aby se e-mail neodeslal dvakrát.

## Související

  - [Autentizace](/cs/docs/api-reference/authentication/): Přístupové údaje, oprávnění a všechny chyby autentizace.
  - [Limity rychlosti](/cs/docs/api-reference/rate-limits/): Limity odesílání, hlavičky a rostoucí odstup.
  - [Idempotence](/cs/docs/api-reference/idempotency/): Opakujte odeslání, aniž byste e-mail poslali dvakrát.
  - [Logy požadavků](/cs/docs/logs/request-logs/): Prohlédněte si požadavek a odpověď každého neúspěšného volání API.

---
Zdroj: https://emailit.com/cs/docs/api-reference/errors/