Chyby
Chyby sdílejí jednu obálku (viz přehled). Větvete logiku podle code, logujte meta.request_id a message berte jako anglický text pro lidi.
Chyby klienta
Sekce “Chyby klienta”| Kód | Stav | Význam a co dělat |
|---|---|---|
validation_failed |
400 | Pole neprošlo validací. field ho uvádí, details vysvětluje. Opravte pole. |
bad_request |
400 | Požadavek vůbec nešlo přečíst: poškozený JSON, rozbitý stream Content-Encoding, přerušené tělo. Není co opravit v polích; zkontrolujte přenos. |
validation_error |
400 | X-Account-Id bylo odesláno na endpoint, který ho zakazuje (/auth/login, /auth/refresh, /auth/swap-company, /auth/logout). |
cursor_expired |
400 | Kurzor stránkování je starší než 24 hodin. Začněte výpis znovu. |
unauthenticated |
401 | Chybějící nebo neplatný token. Obnovte relaci nebo zkontrolujte klíč. |
invalid_signature |
401 | Podpis webhooku neprošel ověřením. Viz Webhooky. |
forbidden |
403 | Token je platný, ale chybí mu oprávnění. |
account_context_mismatch |
403 | X-Account-Id neodpovídá účtu tokenu. Klient má zastaralou představu o aktuální firmě; načtěte ji znovu z relace. |
not_found |
404 | Zdroj neexistuje nebo patří jinému účtu či webu. API tyto případy nikdy nerozlišuje. |
conflict |
409 | Konflikt stavu: optimistický zámek, omezení jedinečnosti nebo akce, která v aktuálním stavu není povolena (například zápis do sloučené konverzace). |
idempotency_key_conflict |
409 | Idempotency-Key byl znovu použit s jiným tělem. |
payload_too_large |
413 | Tělo překračuje limit pro tuto rodinu endpointů. |
unsupported_media_type |
415 | Nesprávný Content-Type. |
unprocessable |
422 | Platný JSON, ale obchodní pravidlo ho odmítlo (například termín rezervace mimo pracovní dobu). |
storage_quota_exceeded |
422 | Účet dosáhl limitu úložiště svého tarifu. details obsahuje used_bytes, quota_bytes a requested_bytes; uvolněte místo nebo přejděte na vyšší tarif. |
rate_limited |
429 | Zpomalte. Respektujte Retry-After a details.retry_after_seconds. |
Chyby serveru
Sekce “Chyby serveru”| Kód | Stav | Význam a co dělat |
|---|---|---|
internal_error |
500 | Neočekávané selhání. Zkuste to jednou znovu, pak kontaktujte podporu s request_id. |
upstream_unavailable |
502 | Brána se ke službě vůbec nedostala. Krátké opakování obvykle uspěje. |
service_unavailable |
503 | Plánovaná údržba nebo otevřený jistič (circuit breaker). Opakujte po době z hlavičky Retry-After. |
ai_vendor_out_of_funds |
503 | Váš poskytovatel AI odmítl volání z fakturačních důvodů (402 nebo kvótová 429 od poskytovatele). Dobijte účet u poskytovatele; opakování nepomůže. |
upstream_timeout |
504 | Služba neodpověděla včas. Opakujte, pokud je přítomno retry_after. |
Opakování
Sekce “Opakování”Opakujte 429, 502, 503, 504 a síťová selhání s exponenciálně rostoucí prodlevou a při opakování posílejte stejný Idempotency-Key, aby se zápis nikdy neprovedl dvakrát. Neopakujte 4xx kromě 429.