오류

오류는 하나의 봉투를 공유합니다(개요 참고). code로 분기하고, meta.request_id를 기록하고, message는 사람이 읽는 영어 텍스트로 취급하세요.

클라이언트 오류

코드	상태	의미와 대처 방법
validation_failed	400	필드가 검증에 실패했습니다. field가 그 필드를 가리키고 details가 설명합니다. 필드를 수정하세요.
bad_request	400	요청을 전혀 읽을 수 없습니다: 잘못된 JSON, 손상된 Content-Encoding 스트림, 중단된 본문. 수정할 필드가 없으니 전송 과정을 확인하세요.
validation_error	400	X-Account-Id를 금지하는 엔드포인트(/auth/login, /auth/refresh, /auth/swap-company, /auth/logout)에 보냈습니다.
cursor_expired	400	페이지네이션 커서가 24시간보다 오래되었습니다. 목록 조회를 처음부터 다시 시작하세요.
unauthenticated	401	토큰이 없거나 유효하지 않습니다. 세션을 갱신하거나 키를 확인하세요.
invalid_signature	401	웹훅 서명이 검증되지 않았습니다. 웹훅을 참고하세요.
forbidden	403	토큰은 유효하지만 권한이 없습니다.
account_context_mismatch	403	X-Account-Id가 토큰의 계정과 일치하지 않습니다. 클라이언트가 알고 있는 현재 회사가 어긋났으니 세션에서 다시 읽으세요.
not_found	404	리소스가 없거나 다른 계정 또는 사이트에 속합니다. API는 두 경우를 절대 구분하지 않습니다.
conflict	409	상태 충돌: 낙관적 잠금, 고유 제약 조건, 또는 현재 상태에서 허용되지 않는 작업(예: 병합된 대화에 쓰기).
idempotency_key_conflict	409	Idempotency-Key가 다른 본문으로 재사용되었습니다.
payload_too_large	413	본문이 이 엔드포인트 그룹의 한도를 넘었습니다.
unsupported_media_type	415	Content-Type이 잘못되었습니다.
unprocessable	422	유효한 JSON이지만 비즈니스 규칙에 의해 거부되었습니다(예: 근무 시간 외의 예약 시간).
storage_quota_exceeded	422	계정이 플랜의 저장 공간 한도에 도달했습니다. details에 used_bytes, quota_bytes, requested_bytes가 담깁니다. 공간을 비우거나 업그레이드하세요.
rate_limited	429	요청 속도를 줄이세요. Retry-After와 details.retry_after_seconds를 따르세요.

서버 오류

코드	상태	의미와 대처 방법
internal_error	500	예기치 않은 오류입니다. 한 번 재시도한 뒤 request_id와 함께 지원팀에 문의하세요.
upstream_unavailable	502	게이트웨이가 서비스에 전혀 도달하지 못했습니다. 잠시 후 재시도하면 대개 성공합니다.
service_unavailable	503	계획된 유지보수이거나 서킷 브레이커가 열려 있습니다. Retry-After 헤더에 따라 재시도하세요.
ai_vendor_out_of_funds	503	AI 제공업체가 결제 문제로 호출을 거부했습니다(공급업체의 402 또는 할당량 429). 공급업체 계정을 충전하세요. 재시도해도 해결되지 않습니다.
upstream_timeout	504	서비스가 제시간에 응답하지 않았습니다. retry_after가 있으면 재시도하세요.

재시도

429, 502, 503, 504와 네트워크 오류는 지수 백오프로 재시도하고, 재시도할 때 같은 Idempotency-Key를 보내 쓰기 작업이 두 번 적용되지 않게 하세요. 429 이외의 4xx는 재시도하지 마세요.