Chyby

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:

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

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:

{
  "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, 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:

{
  "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:

Chyby validace při odesílání

Odeslání e-mailu a Přeposlání e-mailu kontrolují celou zprávu najednou a všechny problémy vracejí v poli validation_errors:

{
  "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í:

{
  "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.

{
  "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

Časté chyby a jejich řešení

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.
• 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, aby se e-mail neodeslal dvakrát.

Související