소셜 미디어 게시물이 실패한 것처럼 보일 때, 즉시 다시 전송하지 마세요. 먼저 해당 게시물이 수락 전 거절되었는지, 수락 후 확실히 실패했는지, 타임아웃 (Timeout)에도 불구하고 성공했을 가능성이 있는지, 또는 이미 공개되었는지 확인하십시오. 증거를 대조하고 원인을 수정하세요. 재시도는 시도 시 동일한 승인된 콘텐츠, 계정 및 타이밍을 사용하는 경우에만 수행해야 합니다.

타임아웃 (Timeout)은 위험한 사례입니다. 게시 시스템 또는 제공업체가 연결이 끊기기 전에 요청을 수락했을 수 있습니다. 다시 전송하면 중복 게시물이 생성될 수 있으므로, 먼저 알려진 게시 상태를 확인하고 목적지를 점검하십시오.

개발자와 운영자는 아래의 단계 모델 (stage model), 의사 결정 트리 (decision tree) 및 실패 로그 (failure log)를 사용하여 에이전트 기반의 게시 시도를 복구할 수 있습니다. 에이전트가 API, CLI 또는 기타 지원되는 클라이언트를 통해 커넥터 (connector)를 호출하든 관계없이 동일한 프로세스가 적용됩니다.

게시를 4가지 체크포인트로 취급하기

복구 과정을 사전 점검 (preflight), 제출 (submission), 제공업체 전달 (provider delivery), 그리고 대조 (reconciliation)로 분리하십시오. "게시가 실패했다"라는 말은 다음에 무엇을 해야 할지 결정하기에 너무 모호합니다.

1. 사전 점검 (Preflight)

무엇인가를 제출하기 전에, 사전 점검 (preflight)을 사용하여 의도한 작업이 유효한지 확인하십시오. 라이브 통합 (live integration)과 그 설정 스키마 (settings schema)를 파악한 다음, 계정, 콘텐츠, 미디어, 목적지별 설정 및 의도한 시간을 확인하십시오.

미디어가 포함된 게시물의 경우, 먼저 각 에셋 (asset)을 업로드하고 업로드 작업에 의해 반환된 Groniz 경로 또는 참조를 유지하십시오. 로컬 파일 이름이나 임의의 URL은 해당 참조를 대체할 수 없습니다. multi-platform media upload guide에서 해당 순서를 설명합니다.

이 체크포인트에서의 유효성 검사 거절 (validation rejection)은 명확합니다. 어떠한 게시 요청도 제출 경계를 넘지 않았어야 합니다. 잘못된 입력을 수정하고, 사전 점검 (preflight)을 반복하며, 승인 바인딩 (approval binding)을 온전하게 유지하십시오.

2. 제출 (Submission)

제출 (submission) 단계에서 게시 시스템은 게시물을 예약하거나 전송하라는 요청을 받습니다. 다른 조치를 취하기 전에 해당 시도와 그 결과를 기록하십시오.

수락(Acceptance)은 요청이 워크플로(workflow)에 진입했다는 것만을 보여줄 뿐, 제공자(provider)가 게시물을 실제로 게시했다는 것을 의미하지는 않습니다. 타임아웃(timeout)이나 연결 끊김(broken connection) 또한 거절(rejection)을 증명하지 않습니다. 응답이 유실되기 전에 수신 측에서 요청을 수락했을 수도 있기 때문입니다.

아무것도 수락되지 않았다는 확실한 증거가 없는 한, 전송 오류(transport errors)는 모호한 상태로 취급하십시오. "성공 응답을 받지 못했다"를 "게시물이 확실히 실패했다"로 단정 지어서는 안 됩니다.

3. 제공자 전달 (Provider delivery)

제공자 전달 단계에서는 목적지(destination)가 게시물을 수락하고 게시할지 여부를 결정합니다. 이전 검증(validation) 단계를 통과한 작업이라도 거절될 수 있습니다. 텍스트 형식, 미디어 지원, 예약(scheduling) 동작 및 필수 설정은 32개 이상의 네트워크마다 서로 다릅니다.

Groniz는 이러한 네트워크 전반에 걸쳐 OAuth, 플랫폼별 포맷팅(formatting), 예약(scheduling) 및 전달(delivery)을 처리하지만, 제공자들은 여전히 서로 다르게 동작합니다. 한 채널은 실패하고 다른 채널은 성공하는 경우, 해당 채널의 목적지(destination)와 단계(stage)를 기록하십시오.

4. 화해/조정 (Reconciliation)

화해(Reconciliation) 단계는 호출자(caller)가 관찰한 내용과 실제로 일어난 일을 비교합니다. 지원되는 워크플로(workflow)를 통해 알려진 게시물 상태를 나열하거나 확인한 다음, 가능한 경우 목적지(destination)를 조사하십시오. 공개된 결과가 승인된 콘텐츠, 계정 및 의도된 게시 시간과 일치하는지 비교합니다.

이 단계는 모호한 타임아웃(timeout)을 안전하게 해결할 수 있는 유일한 체크포인트(checkpoint)입니다. 게시물이 공개 상태라면, 확인된 게시를 기록하고 중단하십시오. 공개 상태가 아니지만 가용한 상태만으로 실패를 증명할 수 없다면, 조사를 위해 에스컬레이션(escalate)하십시오.

이러한 경계에 대한 더 넓은 관점은 AI agent social media publishing lifecycle 및 scheduling architecture for AI agents를 참조하십시오.

실패 복구 결정 트리 (Failure recovery decision tree)

성공 응답이 아니거나 전달 확인이 누락된 경우마다 이 트리를 사용하십시오:

시작: 예상된 게시물이 아직 확인되지 않음
|
+-- 사전 점검(preflight) 또는 제출(submission)에서 명확한 검증 거절(validation rejection)이 반환되었습니까?
...

"안전한 재시도 (Safe retry)"는 운영상의 결정이지, API 요청이 멱등성 (idempotency)을 가진다는 주장이 아닙니다. 이는 다른 제출 (submission)을 수행하기 전에 게시되지 않았음을 확인하고 승인 엔벨로프 (approval envelope)가 변경되지 않았음을 요구함으로써 중복 위험을 줄입니다.

복사 가능한 실패 로그 템플릿

실패 기록을 자체 애플리케이션이나 인시던트 (incident) 시스템에 저장하십시오. 아래 필드들은 운영자에게 속하는 것입니다. 이는 Groniz의 응답 필드나 API 스키마 (schema)가 아닙니다.

incident_id: ""
opened_at: ""
operator_or_agent: ""
...

콘텐츠 핑거프린트 (content fingerprint)는 운영자가 시도 (attempts)를 비교하는 데 도움이 되는 애플리케이션 측의 안정적인 참조 값일 수 있습니다. 이는 제공자 측의 중복 제거 키 (deduplication key)가 아닙니다. 내부 인시던트 ID (incident ID)는 증거를 상관 분석 (correlate)할 수 있지만, 게시 API 요청을 멱등하게 만들지는 않습니다.

각 결과별 처리 방법

검증 거절 (Validation rejection)

실패한 규칙과 정확한 단계를 기록하십시오. 목적지에 대한 캐시된 가정 (cached assumptions)이 틀릴 수 있으므로, 요청을 수정하기 전에 라이브 통합 (live integration) 및 설정 스키마 (settings schema)를 새로고침하십시오. 기존 참조가 유효하지 않거나 에셋 (asset) 자체를 변경해야 하는 경우에만 미디어를 다시 업로드하십시오.

만약 수정을 통해 문구, 미디어, 계정, 목적지 또는 게시 타이밍이 변경된다면, 해당 작업은 더 이상 승인된 내용과 일치하지 않습니다. AI 소셜 게시물을 위한 인간의 승인 (human approval for AI social posts)에 설명된 프로세스를 통해 다시 제출하십시오. 겉보기에 기계적인 검증 수정이라 할지라도 게시되는 내용을 변경할 수 있습니다.

확인된 실패 (Confirmed failure)

명확한 제공자 거절 (provider rejection) 또는 게시되지 않았음을 확정적으로 보고하는 알려진 상태를 통해 실패를 확립할 수 있습니다. 응답이 누락된 상태로는 실패를 확립할 수 없습니다.

다른 시도를 하기 전에 원인을 찾아 수정하십시오. 수정 작업에는 유효하지 않은 구성의 새로고침, 호환되지 않는 미디어 에셋 교체 또는 의도한 계정의 재연결이 포함될 수 있습니다. 모든 제공자에 대해 하나의 오류 분류 체계 (error taxonomy)를 하드코딩하는 대신, 라이브 스키마 (live schema)와 지원되는 워크플로 (workflow)를 따르십시오.

프리플라이트 (preflight) 및 안전한 재시도 (safe-retry) 체크를 다시 실행하십시오. 통제된 단일 시도를 제출하고, 이를 기록한 뒤, 조정 (reconciliation) 단계로 돌아가십시오.

모호한 결과 (Ambiguous outcome)

모든 재시도 (retry)를 중단하십시오. 타임스탬프 (timestamps), 호출자 관찰 내용 (caller observations), 반환된 모든 참조 (reference), 그리고 승인된 엔벨로프 (approved envelope)를 보존하십시오. 알려진 상태 (known state)를 목록화하거나 확인한 다음, 의도된 목적지 (destination)와 계정 (account)을 조사하십시오.

의도된 게시 시간대 (publication window) 주변에서 예상되는 콘텐츠를 검색하십시오. 만약 목적지의 포맷팅 (formatting)이 변경될 수 있다면, 텍스트뿐만 아니라 계정, 미디어, 그리고 타이밍 (timing)도 함께 비교하십시오. 목적지에서 제공하는 증거가 너무 적고 알려진 상태가 여전히 불분명하다면, 해당 인시던트 (incident)를 운영자 검토를 위해 대기시키십시오. 불확실성은 재전송을 허용하는 권한이 아닙니다.

게시 확인됨 (Confirmed publication)

가능한 경우 공개 게시물 참조 (public post reference)를 캡처하고, 언제 확인되었는지 기록한 뒤 인시던트 (incident)를 종료하십시오. 원래의 호출자가 타임아웃 (timeout)되었거나 로컬 워커 (local worker)가 여전히 오류를 보고한다는 이유만으로 재시도하지 마십시오. 공개 게시물이 완료되면 전달 문제는 해결된 것입니다.

증거를 기반으로 한 재시도 워커 (retry worker) 구축

재시도 워커 (retry worker)는 단순히 오류만을 받는 것이 아니라, 복구 결정 (recovery decision)을 받아야 합니다. 워커의 입력값에는 승인된 엔벨로프 (approved envelope), 분류 (classification), 수정 증거 (correction evidence), 그리고 조정 (reconciliation) 결과가 포함되어야 하며, 이를 통해 모든 실패한 작업을 맹목적으로 다시 실행하는 것을 방지해야 합니다.

다음 세 가지 게이트 (gates)를 강제하십시오:

1. 원인 게이트 (Cause gate): 기록된 실패 원인이 수정되었는지 확인합니다.
2. 게시 게이트 (Publication gate): 조정 (reconciliation)을 통해 예상되는 게시물이 이미 공개 상태가 아님을 확인합니다.
3. 승인 게이트 (Approval gate): 콘텐츠, 계정, 목적지, 그리고 타이밍 (timing)이 승인된 작업과 여전히 일치하는지 확인합니다.

재시도 후, 워커는 반드시 조정 (reconciliation) 단계로 돌아가야 합니다. 요청 수락 (request acceptance)이 전달 (delivery)을 증명하는 것은 아닙니다.

이 설계는 자동 재시도 (automatic retries), 보장된 멱등성 (guaranteed idempotency), 웹훅 (webhooks), 데드 레터 큐 (dead-letter queue), 또는 특정 상태 및 오류 필드에 대해 어떠한 가정도 하지 않습니다. 그러한 동작은 일반적인 작업 처리 패턴이 아니라, 현재 문서화된 계약 (contract)에 따라 이루어져야 합니다.

Groniz의 공개 API (public API)는 통합 목록 조회 (listing integrations), 다음 슬롯 찾기 (finding the next slot), 미디어 업로드 (uploading media), 그리고 게시물 예약 (scheduling), 목록 조회 (listing) 또는 삭제 (deleting) 작업을 문서화합니다. 단계별 검증 (stage checks)을 위해 해당 작업들을 사용하고, 제공자별 설정 (provider-specific settings)은 라이브 통합 (live integration)에 연결된 상태로 유지하십시오.

현재의 계약 (contract)에 따라 이러한 복구 루프 (recovery loop)를 구축하려면, Groniz 공개 API 문서 (Groniz Public API documentation)부터 시작하십시오.