Virheet

Virheillä on yhteinen kirjekuori (katso yleiskatsaus). Haaraudu code-arvon perusteella, kirjaa meta.request_id lokiin ja käsittele message-kenttää ihmisille tarkoitettuna englanninkielisenä tekstinä.

Asiakasvirheet

Koodi	Tila	Merkitys ja mitä tehdä
validation_failed	400	Kenttä ei läpäissyt validointia. field nimeää sen; details selittää. Korjaa kenttä.
bad_request	400	Pyyntöä ei voitu lukea lainkaan: virheellinen JSON, rikkinäinen Content-Encoding-virta, keskeytynyt runko. Korjattavaa kenttää ei ole; tarkista tiedonsiirto.
validation_error	400	X-Account-Id lähetettiin päätepisteeseen, joka kieltää sen (/auth/login, /auth/refresh, /auth/swap-company, /auth/logout).
cursor_expired	400	Sivutuskursori on yli 24 tuntia vanha. Aloita luettelointi alusta.
unauthenticated	401	Puuttuva tai virheellinen tunniste. Päivitä istunto tai tarkista avain.
invalid_signature	401	Webhookin allekirjoitusta ei voitu todentaa. Katso Webhookit.
forbidden	403	Tunniste on kelvollinen, mutta siltä puuttuu oikeus.
account_context_mismatch	403	X-Account-Id ei vastaa tunnisteen tiliä. Asiakasohjelman käsitys nykyisestä yrityksestä on muuttunut; lue se uudelleen istunnosta.
not_found	404	Resurssia ei ole olemassa tai se kuuluu toiselle tilille tai sivustolle. API ei koskaan erottele näitä.
conflict	409	Tilaristiriita: optimistinen lukitus, yksilöllisyysrajoite tai toiminto, jota nykyinen tila ei salli (esimerkiksi kirjoittaminen yhdistettyyn keskusteluun).
idempotency_key_conflict	409	Idempotency-Key käytettiin uudelleen eri rungolla.
payload_too_large	413	Runko ylittää tämän päätepisteperheen rajan.
unsupported_media_type	415	Väärä Content-Type.
unprocessable	422	Kelvollinen JSON, mutta liiketoimintasääntö hylkäsi sen (esimerkiksi varausaika aukioloaikojen ulkopuolella).
storage_quota_exceeded	422	Tili saavutti pakettinsa tallennustilarajan. details sisältää used_bytes, quota_bytes ja requested_bytes; vapauta tilaa tai päivitä paketti.
rate_limited	429	Hidasta. Noudata Retry-After- ja details.retry_after_seconds-arvoja.

Palvelinvirheet

Koodi	Tila	Merkitys ja mitä tehdä
internal_error	500	Odottamaton virhe. Yritä kerran uudelleen ja ota sitten yhteyttä tukeen request_id-arvon kanssa.
upstream_unavailable	502	Yhdyskäytävä ei tavoittanut palvelua lainkaan. Lyhyt uusintayritys yleensä onnistuu.
service_unavailable	503	Suunniteltu huolto tai avoin katkaisija (circuit breaker). Yritä uudelleen Retry-After-otsakkeen jälkeen.
ai_vendor_out_of_funds	503	AI-palveluntarjoajasi hylkäsi kutsun laskutussyistä (palveluntarjoajalta 402 tai kiintiön 429). Lisää saldoa palveluntarjoajan tilille; uusintayritys ei auta.
upstream_timeout	504	Palvelu ei vastannut ajoissa. Yritä uudelleen, kun retry_after on mukana.

Uusintayritykset

Yritä uudelleen 429-, 502-, 503- ja 504-vastausten sekä verkkovirheiden jälkeen eksponentiaalisella viiveellä, ja lähetä uusintayrityksessä sama Idempotency-Key, jotta kirjoitusta ei koskaan sovelleta kahdesti. Älä yritä uudelleen muita 4xx-vastauksia kuin 429.