검토 2026-11-10 · API 버전 2026-11-09 · Markdown 읽기
오류, 재시도, 복구
API 오류는 선택적인 필드 오류, 수신처 오류, 재시도 힌트, 작업 핸드오프와 함께
{ "error": { "code": "…", "message": "…", "requestId": "…" } }를 사용해요.
지원 요청 시 requestId를 보존하세요. 진단 정보를 수집할 때 자격 증명, 서명된
업로드 URL, 민감한 요청 콘텐츠는 로그에 남기지 마세요.
| 응답 | 복구 |
|---|---|
401 unauthenticated | 누락, 잘못된 형식, 폐기된 product key 확인 |
403 forbidden_scope / account_not_allowed | 키 스코프와 수신처 접근 검토 |
402 account_limit, seat_limit, storage_limit | 워크스페이스 권한과 리소스 사용 검토 |
402 subscription_inactive / trial_expired | 결제 상태 해결; 초안과 대기 작업 보존 |
409 revision_conflict | 현재 버전을 읽고, 변경 사항을 검토하고, 의도적으로 다시 적용 |
409 idempotency_conflict | 키가 다른 본문으로 재사용됨; 원래 작업과 조정 |
409 consent_required | 권한 있는 사람에게 제공된 검토 핸드오프 완료 요청 |
409 too_late_to_cancel | 실제 전송 상태 확인; 취소 성공을 주장하지 않기 |
media_expired / media_deleting | 원본을 다시 업로드하고 초안 업데이트 |
422 validation_failed | 구조화된 필드나 수신처별 문제 수정 |
429 rate_limited | Retry-After 존중; 동시성을 줄이고 백오프 사용 |
submission_unknown | 다른 제출을 시도하기 전에 기존 외부 결과 조정 |
안전한 변경 재시도
첫 변경 전에 멱등 키를 생성하고 정확한 요청을 저장하세요. 응답을 잃어버리면
작업이 이미 성공했을 수 있어요. 같은 키로 같은 요청을 재생하세요; 네트워크가
타임아웃됐다는 이유만으로 새 키를 만들지 마세요. MCP 변경 도구는
transport_outcome_unknown 실패를 포함해 자기 키를 결과에 그대로 돌려줘요.
어댑터는 변경 작업을 자동 재시도하지 않아요.
기술적 워크스페이스 속도 제한은 게시 크레딧이 아니에요. 현재 플랜과 속도 정보는
/usage를 사용하세요. 일시적 오류에만 적절할 때 백오프하세요; 원인을 바꾸지
않고 인증, 검증, 사람 동의 오류를 재시도해도 도움이 되지 않아요.
부분 성공과 관찰
수락된 게시/예약 배치는 독립적인 전송의 집합이에요. 성공한 영수증과 네이티브 링크를 보관하세요. 실패한 수신처는 배치 전체를 다시 만드는 대신 자체 재시도 엔드포인트로 복구하세요. 서명된 webhooks를 권장해요; 폴링한다면 점점 길어지는 지연으로 제한된 시도 횟수를 사용하고 해결되지 않은 작업을 사람에게 알리세요.