가이드운영 안내
오류와 부분 실패
오류 메시지와 계정별 결과를 읽고 다음 작업을 결정하세요.
에러 형식
요청 자체가 거부되면 다음 공통 오류 형식을 사용합니다. 코드뿐 아니라 message도 확인하세요.
{
"error": {
"code": "UNAUTHENTICATED",
"message": "Missing or invalid API key."
}
}상태 코드
| HTTP | 코드 | 해결 방법 |
|---|---|---|
| 401 | UNAUTHENTICATED | Bearer 헤더와 키 폐기 여부를 확인하세요. |
| 403 | BLOCKED | 사용자가 차단되었습니다. Posteady 지원에 문의하세요. |
| 403 | PLAN_REQUIRED | 크리에이터 이상인 적격 워크스페이스를 사용하세요. |
| 403 | INSUFFICIENT_PERMISSION | 워크스페이스 소유자에게 현재 작업 권한 확인을 요청하세요. |
| 404 | ACCOUNT_NOT_FOUND / POST_NOT_FOUND | ID와 키의 워크스페이스를 확인하세요. 리소스가 더 이상 없을 수 있습니다. |
| 409 | ACCOUNT_TOKEN_EXPIRED | Posteady에서 소셜 계정을 다시 연결하세요. |
| 409 | ALREADY_REPOSTED | 이미 리포스트한 원본입니다. 반복 요청하지 마세요. |
| 409 | REQUEST_CONFLICT | 같은 requestId에는 저장한 입력을 사용하고 새 작업에만 새 ID를 쓰세요. |
| 409 | POST_NOT_CANCELLABLE | 전송을 시작했거나 취소할 수 없는 작업입니다. 상태를 확인하세요. |
| 422 | VALIDATION_ERROR | 오류 메시지를 읽고 플랫폼 입력 형식과 비교하세요. |
| 429 | RATE_LIMITED | 호출 간격을 두고 속도 제한 윈도우가 지나기를 기다리세요. |
| 429 | QUOTA_EXCEEDED | 메시지에서 월 사용량과 미디어 저장 공간을 구분하세요. |
| 500 | INTERNAL_ERROR | 예기치 못한 서버 오류입니다. 쓰기 요청은 결과를 확인한 후 재시도하세요. |
| 502 | PLATFORM_ERROR | 플랫폼이 작업을 거부했습니다. 메시지와 연결 상태를 확인하세요. |
| 503 | SERVICE_UNAVAILABLE | Facebook 신규 쓰기가 일시적으로 비활성입니다. 기존 작업 조회·취소는 제공됩니다. |
부분 실패
발행·예약 요청의 계정별 실패는 최상위 error 대신 results 안에 나타날 수 있습니다. 텍스트 요청에서 일부 계정이 성공하면 HTTP 200으로 다음처럼 응답합니다.
{
"results": [
{
"accountId": "11111111-1111-4111-8111-111111111111",
"provider": "threads",
"username": "example",
"success": true,
"postIds": [
"18000000000000000"
]
},
{
"accountId": "77777777-7777-4777-8777-777777777777",
"provider": "x",
"username": "example_x",
"success": false,
"postIds": [],
"error": "Example platform failure"
}
],
"summary": {
"succeeded": 1,
"failed": 1
}
}모든 텍스트 대상이 실패하면 HTTP 502이지만 같은 결과 형식을 유지합니다. 각 success·postIds·error를 확인하고 이미 성공한 계정이나 체인 부분을 재발행하지 않도록 처리하세요.
비동기 작업 오류
HTTP 202 이후에도 작업이 실패할 수 있습니다. GET /publish-jobs/{id}의 status·error.code·error.message를 확인하세요. 작업 내부 오류 코드는 위 HTTP 오류 표와 다를 수 있습니다. Facebook terminal 재조회는 실패 상태에서도 HTTP 200이므로 success와 status를 함께 봐야 합니다.