Mga error

Iisang envelope ang ginagamit ng mga error (tingnan ang pangkalahatang-ideya). Mag-branch ayon sa code, i-log ang meta.request_id, at ituring ang message bilang English na teksto para sa mga tao.

Mga error ng client

Code	Status	Kahulugan at ano ang gagawin
validation_failed	400	Hindi pumasa sa validation ang isang field. Pinapangalanan ito ng field; ipinapaliwanag ng details. Ayusin ang field.
bad_request	400	Hindi mabasa ang request: sirang JSON, sirang stream ng Content-Encoding, naputol na body. Walang field na aayusin; suriin ang transport.
validation_error	400	Ipinadala ang X-Account-Id sa endpoint na nagbabawal nito (/auth/login, /auth/refresh, /auth/swap-company, /auth/logout).
cursor_expired	400	Mas matanda sa 24 oras ang pagination cursor. Simulan ulit ang listahan.
unauthenticated	401	Nawawala o hindi valid ang token. I-refresh ang session o suriin ang key.
invalid_signature	401	Hindi na-verify ang signature ng webhook. Tingnan ang Mga webhook.
forbidden	403	Valid ang token pero kulang ito ng pahintulot.
account_context_mismatch	403	Hindi tugma ang X-Account-Id sa account ng token. Lumihis ang pagkakaalam ng client sa kasalukuyang kumpanya; basahin ulit ito mula sa session.
not_found	404	Hindi umiiral ang resource o kabilang ito sa ibang account o site. Hindi kailanman pinagkakaiba ng API ang dalawa.
conflict	409	Salungatan sa state: optimistic lock, unique constraint, o aksyong hindi pinapayagan sa kasalukuyang state (halimbawa, pagsulat sa na-merge na usapan).
idempotency_key_conflict	409	Muling ginamit ang Idempotency-Key na may ibang body.
payload_too_large	413	Lumampas ang body sa limitasyon para sa pamilya ng endpoint na ito.
unsupported_media_type	415	Maling Content-Type.
unprocessable	422	Valid na JSON, pero tinanggihan ito ng isang business rule (halimbawa, booking slot na nasa labas ng oras ng trabaho).
storage_quota_exceeded	422	Naabot ng account ang limitasyon sa storage ng plan nito. Dala ng details ang used_bytes, quota_bytes at requested_bytes; magbakante ng espasyo o mag-upgrade.
rate_limited	429	Magdahan-dahan. Sundin ang Retry-After at details.retry_after_seconds.

Mga error ng server

Code	Status	Kahulugan at ano ang gagawin
internal_error	500	Hindi inaasahang pagkabigo. Subukan ulit nang isang beses, tapos makipag-ugnayan sa suporta kasama ang request_id.
upstream_unavailable	502	Hindi talaga maabot ng gateway ang serbisyo. Kadalasang nagtatagumpay ang maikling retry.
service_unavailable	503	Nakaplanong maintenance o bukas na circuit breaker. Subukan ulit pagkatapos ng header na Retry-After.
ai_vendor_out_of_funds	503	Tinanggihan ng AI provider mo ang tawag dahil sa billing (402 o quota na 429 mula sa vendor). Mag-top up sa account ng vendor; hindi makakatulong ang retry.
upstream_timeout	504	Hindi sumagot sa oras ang serbisyo. Subukan ulit kapag may retry_after.

Pag-retry

I-retry ang 429, 502, 503, 504 at mga pagkabigo sa network nang may exponential backoff, at ipadala ang parehong Idempotency-Key sa retry para hindi kailanman mailapat nang dalawang beses ang isang write. Huwag i-retry ang 4xx maliban sa 429.