Xətalar

Xətalar vahid zərfi paylaşır (baxın: icmal). Məntiqinizi code üzrə budaqlandırın, meta.request_id dəyərini loglayın və message sahəsinə insanlar üçün ingilis dilində mətn kimi yanaşın.

Müştəri xətaları

Kod	Status	Mənası və nə etməli
validation_failed	400	Sahə yoxlamadan keçmədi. field onun adını göstərir; details izah edir. Sahəni düzəldin.
bad_request	400	Sorğu ümumiyyətlə oxuna bilmədi: səhv JSON, pozulmuş Content-Encoding axını, yarımçıq kəsilmiş gövdə. Düzəldiləcək sahə yoxdur; ötürməni yoxlayın.
validation_error	400	X-Account-Id onu qadağan edən endpoint-ə göndərilib (/auth/login, /auth/refresh, /auth/swap-company, /auth/logout).
cursor_expired	400	Səhifələmə kursoru 24 saatdan köhnədir. Siyahını yenidən başladın.
unauthenticated	401	Token yoxdur və ya etibarsızdır. Sessiyanı yeniləyin və ya açarı yoxlayın.
invalid_signature	401	Webhook imzası yoxlamadan keçmədi. Baxın: Webhook-lar.
forbidden	403	Token etibarlıdır, lakin icazəsi yoxdur.
account_context_mismatch	403	X-Account-Id tokenin hesabına uyğun gəlmir. Müştərinin cari şirkət haqqında təsəvvürü sürüşüb; onu sessiyadan yenidən oxuyun.
not_found	404	Resurs mövcud deyil və ya başqa hesaba və ya sayta aiddir. API bu ikisini heç vaxt fərqləndirmir.
conflict	409	Vəziyyət ziddiyyəti: optimistik kilid, unikallıq məhdudiyyəti və ya cari vəziyyətdə icazə verilməyən əməliyyat (məsələn, birləşdirilmiş söhbətə yazmaq).
idempotency_key_conflict	409	Idempotency-Key fərqli gövdə ilə təkrar istifadə olunub.
payload_too_large	413	Gövdə bu endpoint ailəsi üçün limiti aşır.
unsupported_media_type	415	Yanlış Content-Type.
unprocessable	422	JSON düzgündür, lakin biznes qaydası onu rədd edib (məsələn, iş saatlarından kənar bron vaxtı).
storage_quota_exceeded	422	Hesab planının yaddaş limitinə çatıb. details used_bytes, quota_bytes və requested_bytes daşıyır; yer boşaldın və ya planı yüksəldin.
rate_limited	429	Sürəti azaldın. Retry-After və details.retry_after_seconds dəyərlərinə əməl edin.

Server xətaları

Kod	Status	Mənası və nə etməli
internal_error	500	Gözlənilməz uğursuzluq. Bir dəfə təkrar cəhd edin, sonra request_id ilə dəstəyə müraciət edin.
upstream_unavailable	502	Şlüz xidmətə heç çata bilmədi. Qısa təkrar cəhd adətən uğurlu olur.
service_unavailable	503	Planlı texniki xidmət və ya açıq circuit breaker. Retry-After başlığındakı müddətdən sonra təkrar cəhd edin.
ai_vendor_out_of_funds	503	AI provayderiniz çağırışı ödəniş səbəbindən rədd etdi (provayderdən 402 və ya kvota 429). Provayder hesabını artırın; təkrar cəhd kömək etməyəcək.
upstream_timeout	504	Xidmət vaxtında cavab vermədi. retry_after mövcud olduqda təkrar cəhd edin.

Təkrar cəhdlər

429, 502, 503, 504 və şəbəkə uğursuzluqlarını eksponensial gecikmə ilə təkrarlayın və təkrar cəhddə eyni Idempotency-Key göndərin ki, yazma əməliyyatı heç vaxt iki dəfə tətbiq olunmasın. 429-dan başqa 4xx xətalarını təkrarlamayın.