Twitter API 오류 코드 및 HTTP 상태 참조

TwexAPI의 Twitter/X API 오류 해결: HTTP 401, 403, 429, 5xx, 유효하지 않은 auth_token, 중복 트윗, DM 한도, 안전한 재시도.

TwexAPI는 Twitter/X API 실패를 HTTP 상태 코드와, 제공되는 경우 업스트림 X 오류 코드로 알립니다. 401은 인증 정보를 수정해야 하고, 403은 접근 권한이나 계정 문제를 해결해야 하며, 429는 요청 제한이 해제될 때까지 기다려야 합니다. 재시도하기 전에 응답 본문을 확인하세요.

이 참조 문서에서 Twitter API 오류 코드, invalid auth_token, 중복 트윗, DM 한도의 해결 방법을 확인할 수 있습니다. 엔드포인트 경로는 현재 API 참조를 따릅니다. MCP 오류, 페이지네이션 복구, SDK 예제는 오류 처리를 참고하세요.

아래 메시지와 업스트림 코드는 문제 해결을 위한 예시입니다. 응답 구조와 HTTP 상태의 대응 관계는 엔드포인트마다 다를 수 있습니다. 엔드포인트 스키마와 실제 응답을 함께 확인하세요.

Twitter API 오류에 맞는 해결 방법 찾기

• HTTP 401 / Invalid auth_token: TwexAPI API 키와 쓰기 엔드포인트에서 사용하는 X 세션 인증 정보를 모두 확인하세요. 인증을 참고하세요.
• HTTP 403: 메시지를 살펴 크레딧 부족, 비공개 게시물, 계정 제한, Premium 요구 사항 중 무엇이 원인인지 확인하세요. 같은 요청을 반복해도 접근 권한은 복구되지 않습니다.
• HTTP 429 / Too Many Requests: Retry-After 또는 retry_after를 따르고, 요청 빈도 제한과 X 계정의 일일 한도를 구분하세요. 요청 제한을 참고하세요.
• HTTP 500 / 502 / 503: 일시적인 읽기 실패는 대기 시간에 상한을 둔 백오프로 재시도하세요. 쓰기를 반복하기 전에 이미 성공했는지 확인하세요.
• X 코드 187, 344, 502: 업스트림 X 코드이며 HTTP 상태 코드와는 별개입니다. Twitter/X 코드 표와 재시도 관련 질문을 확인하세요.

오류 응답 형식

HTTP 상태와 전체 JSON 본문을 보존하세요. TwexAPI 응답에는 code와 msg가 포함될 수 있으며, 요청 검증 오류에는 detail이 사용됩니다.

{
  "code": 500,
  "msg": "Internal server error"
}

{
  "detail": [
    {
      "loc": ["body", "cookie"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

응답에 추가 업스트림 메타데이터가 포함되어 있다면 함께 보존하세요.

• error: 제공되는 경우 오류 메시지입니다. 모든 엔드포인트가 이 필드를 사용한다고 가정하지 마세요.
• twitter_error_code: 제공되는 경우 X 오류 코드입니다. HTTP 상태와는 별개이며, 예를 들어 X 코드 502는 DM 한도를 나타냅니다.
• retry_after: 제공되는 경우 기다려야 할 초 단위 시간입니다. HTTP Retry-After 헤더도 따르세요.

선택적 필드가 반드시 존재한다고 가정하거나 메시지의 정확한 문자열 일치만으로 분기하지 마세요. 본문에 다른 code가 포함되어 있더라도 HTTP 상태가 2xx가 아니면 실패입니다.

일반적인 오류(모든 엔드포인트)

모든 요청에서 다음 조건을 확인하세요. 실제 메시지는 다를 수 있습니다.

Twitter API HTTP 상태 코드

Twitter/X API 오류 코드

응답에 업스트림 X 코드가 포함되어 있다면 다음 의미를 참고하세요. 이는 X 코드이며 HTTP 상태가 아닙니다. 모든 엔드포인트가 twitter_error_code를 노출하는 것은 아닙니다.

트윗 읽기 및 검색

POST /twitter/{screen_name}/timeline/page, /twitter/tweets-replies/page, /twitter/advanced_search/page에 적용됩니다.

게시 및 참여 작업

트윗 작성

POST /twitter/tweets/create

tweet_content, 선택적인 reply_tweet_id, 그리고 cookie에 X 인증 정보를 제공하세요. 트윗 또는 답글 작성을 참고하세요.

좋아요 / 리트윗 / 북마크

POST /twitter/tweets/{tweet_id}/like · /twitter/tweets/{tweet_id}/retweet · /twitter/tweets/{tweet_id}/bookmark

DELETE /twitter/tweets/{tweet_id}/like · /twitter/tweets/{tweet_id}/retweet · /twitter/tweets/{tweet_id}/bookmark

트윗 삭제

POST /twitter/tweets/delete-batch

트윗 하나를 삭제하려면 target_id를 제공하세요. 생략하면 일괄 삭제가 선택됩니다. 오류에서 복구할 때는 원래 요청의 필드를 보존하세요.

팔로우 / 언팔로우

POST /twitter/user/follow · DELETE /twitter/user/follow

프로필 / 아바타 / 배너 업데이트

POST /twitter/profile

이미지 URL에는 profile_image와 profile_banner를, X 인증 정보에는 cookie를 사용하세요.

미디어 첨부

트윗을 작성하거나 DM을 보낼 때 미디어를 첨부하세요. 현재 참조 문서에는 별도의 미디어 업로드 경로가 없습니다. 트윗 작성 시 media_urls는 이미지 최대 4개, GIF 1개 또는 동영상 1개를 지원합니다. GIF/동영상을 다른 미디어와 함께 사용하지 마세요. 접근할 수 없는 URL, 지원되지 않는 형식, 허용되지 않는 파일 크기를 수정한 뒤 재시도하세요. 필드 이름과 제약 조건은 엔드포인트 스키마를 따르세요.

다이렉트 메시지

POST /v3/twitter/send-dm · /v3/twitter/dm-history · /v3/twitter/conversations

권한 확인에는 POST /v2/dm/status를 사용하세요. DM 보내기를 참고하세요.

데이터 읽기

POST /v2/tweet/detail · /twitter/tweets/lookup · /twitter/users/by_ids · /v3/twitter/users/followers · /v3/twitter/users/following · /twitter/tweets/thread_by_id · /twitter/tweets/{tweet_id}/replies/page

GET /twitter/{screen_name}/about · /twitter/search-user/{keyword}/{target_count}

아티클

POST /x/article · GET /x/article/{tweet_id}/markdown

쓰기 작업: POST /x/articles/draft · PUT /x/articles/{article_id}/cover · /x/articles/{article_id}/title · /x/articles/{article_id}/content · POST /x/articles/{article_id}/publish 또는 /x/articles/publish.

아래 Premium 요구 사항은 아티클 게시에 적용됩니다. article_id를 보존하고 실패한 단계만 재시도할 수 있도록 단계별 아티클 작성 흐름을 사용하는 것이 좋습니다.

재시도 안내

팁: 429와 일시적인 5xx에는 지터를 추가하고 대기 시간에 상한을 둔 백오프를 사용하세요. 400/401/403/404/409/422는 먼저 입력, 인증 정보 또는 계정 접근 권한을 수정하세요.

Twitter API 오류 및 재시도 질문

Twitter API가 401 또는 invalid auth_token을 반환하는 이유는 무엇인가요?

HTTP 401은 TwexAPI API 키가 없거나 유효하지 않다는 뜻일 수 있습니다. 쓰기 엔드포인트에서는 Invalid auth_token 또는 X 코드 32가 X 세션이 만료되었다는 뜻일 수도 있습니다. 재시도하기 전에 Bearer 헤더를 수정하거나 cookie로 제공한 X 인증 정보를 갱신하세요.

Twitter API 오류 403과 429는 어떻게 다른가요?

HTTP 403은 크레딧 부족, 비공개 콘텐츠, 제한된 계정, Premium 전용 작업 등의 접근 문제를 나타냅니다. HTTP 429는 요청 또는 계정 한도를 나타냅니다. 403의 원인을 해결하고, 429가 발생하면 안내된 한도가 초기화될 때까지 기다리세요.

Twitter API의 429 Too Many Requests 오류는 어떻게 해결하나요?

Retry-After 또는 retry_after가 제공되면 해당 시간만큼 기다린 뒤, 동시 요청 수를 줄이고 대기 시간에 상한을 둔 백오프로 재개하세요. 일일 트윗 또는 DM 한도는 잠깐 기다리는 것이 아니라 한도가 초기화될 때까지 기다려야 합니다. 읽기를 재시도할 때 실패한 페이지의 커서를 보존하세요.

Twitter 오류 코드 187은 무엇을 의미하나요?

X 오류 코드 187은 트윗 내용이 중복된다는 뜻입니다. 이전 쓰기 작업에서 이미 게시물이 생성되었는지 확인하세요. 다른 게시물을 게시하려는 경우 같은 요청을 반복하는 대신 tweet_content를 변경하세요.

Twitter 오류 코드 344는 무엇을 의미하나요?

X 오류 코드 344는 네트워크 또는 IP와 관련된 일시적인 게시 제한을 나타냅니다. 백오프하고 제공한 프록시를 확인한 뒤, 쓰기를 재시도하기 전에 계정 타임라인을 살펴보세요. 이는 X 오류 코드이며 HTTP 상태 코드가 아닙니다.

Twitter API 오류 500, 502, 503은 재시도해야 하나요?

일시적인 읽기 실패는 지터를 추가하고 대기 시간에 상한을 둔 백오프로 재시도하세요. 쓰기 작업이 시간 초과되거나 5xx를 반환하면 먼저 타임라인, DM 기록 또는 참여 상태를 확인하세요. 실패 응답은 쓰기가 적용되지 않았다는 증거가 아닙니다.

TwexAPI의 422 검증 오류는 재시도해야 하나요?

같은 입력으로 재시도하지 마세요. TwexAPI는 요청 검증 오류에 HTTP 422를 사용합니다. detail에서 실패한 필드, 위치, 유형을 확인하고 엔드포인트 스키마에 따라 요청을 수정하세요.

Twitter 오류 코드 502는 HTTP 502와 같은가요?

아닙니다. X 오류 코드 502는 일일 DM 요청 한도를 나타내며 HTTP 429와 함께 반환될 수 있습니다. HTTP 502는 업스트림 응답 실패를 나타냅니다. 재시도 정책을 선택하기 전에 HTTP 상태와, 제공되는 경우 twitter_error_code를 모두 확인하세요.

관련 페이지

• 오류 처리 — MCP, SDK, 페이지네이션 복구
• 인증 — API 키 및 X 세션 인증 정보
• 요청 제한 — 백오프 및 처리량
• API 개요 — 현재 엔드포인트 참조