Chyby
Chyby zdieľajú jednu obálku (pozrite prehľad). Vetvite logiku podľa code, logujte meta.request_id a message berte ako anglický text pre ľudí.
Chyby klienta
Section titled “Chyby klienta”| Kód | Stav | Význam a čo robiť |
|---|---|---|
validation_failed |
400 | Pole neprešlo validáciou. field ho uvádza, details vysvetľuje. Opravte pole. |
bad_request |
400 | Požiadavku vôbec nebolo možné prečítať: poškodený JSON, pokazený stream Content-Encoding, prerušené telo. Nie je čo opraviť v poliach; skontrolujte prenos. |
validation_error |
400 | X-Account-Id bolo odoslané na endpoint, ktorý ho zakazuje (/auth/login, /auth/refresh, /auth/swap-company, /auth/logout). |
cursor_expired |
400 | Kurzor stránkovania je starší ako 24 hodín. Začnite výpis odznova. |
unauthenticated |
401 | Chýbajúci alebo neplatný token. Obnovte reláciu alebo skontrolujte kľúč. |
invalid_signature |
401 | Podpis webhooku neprešiel overením. Pozrite Webhooky. |
forbidden |
403 | Token je platný, ale chýba mu oprávnenie. |
account_context_mismatch |
403 | X-Account-Id sa nezhoduje s účtom tokenu. Klient má zastarané informácie o aktuálnej firme; načítajte ju znova z relácie. |
not_found |
404 | Zdroj neexistuje alebo patrí inému účtu či webu. API tieto prípady nikdy nerozlišuje. |
conflict |
409 | Konflikt stavu: optimistický zámok, obmedzenie jedinečnosti alebo akcia, ktorá v aktuálnom stave nie je povolená (napríklad zápis do zlúčenej konverzácie). |
idempotency_key_conflict |
409 | Idempotency-Key bol znova použitý s iným telom. |
payload_too_large |
413 | Telo prekračuje limit pre túto rodinu endpointov. |
unsupported_media_type |
415 | Nesprávny Content-Type. |
unprocessable |
422 | Platný JSON, ale obchodné pravidlo ho odmietlo (napríklad termín rezervácie mimo pracovného času). |
storage_quota_exceeded |
422 | Účet dosiahol limit úložiska svojho plánu. details obsahuje used_bytes, quota_bytes a requested_bytes; uvoľnite miesto alebo prejdite na vyšší plán. |
rate_limited |
429 | Spomaľte. Rešpektujte Retry-After a details.retry_after_seconds. |
Chyby servera
Section titled “Chyby servera”| Kód | Stav | Význam a čo robiť |
|---|---|---|
internal_error |
500 | Neočakávané zlyhanie. Skúste to raz znova, potom kontaktujte podporu s request_id. |
upstream_unavailable |
502 | Brána sa k službe vôbec nedostala. Krátke opakovanie zvyčajne uspeje. |
service_unavailable |
503 | Plánovaná údržba alebo otvorený istič (circuit breaker). Opakujte po čase z hlavičky Retry-After. |
ai_vendor_out_of_funds |
503 | Váš poskytovateľ AI odmietol volanie z fakturačných dôvodov (402 alebo kvótová 429 od poskytovateľa). Dobite účet u poskytovateľa; opakovanie nepomôže. |
upstream_timeout |
504 | Služba neodpovedala včas. Opakujte, ak je prítomné retry_after. |
Opakovanie
Section titled “Opakovanie”Opakujte 429, 502, 503, 504 a sieťové zlyhania s exponenciálne rastúcim oneskorením a pri opakovaní posielajte rovnaký Idempotency-Key, aby sa zápis nikdy nevykonal dvakrát. Neopakujte 4xx okrem 429.