X API v2 HTTP 상태 코드
| Code | Text | Description | Troubleshooting tips |
|---|---|---|---|
| 200 | OK | 요청이 성공했습니다! | |
| 400 | Bad Request | 요청이 올바르지 않거나 처리할 수 없습니다. 함께 제공되는 오류 메시지에서 자세히 설명됩니다. 인증이 없거나 잘못된 쿼리 매개변수가 있는 요청은 유효하지 않은 것으로 간주되며 이 응답을 반환합니다. | JSON 쿼리 형식을 다시 확인하세요. 예를 들어 규칙에 정확히 일치 연산자 등과 관련된 큰따옴표 문자가 포함되어 있다면, JSON 구조와 구분하기 위해 백슬래시로 이스케이프해야 할 수 있습니다. |
| 401 | Unauthorized | 요청 인증에 문제가 발생했습니다. 누락되었거나 잘못된 인증 자격 증명 때문일 수 있습니다. 정의되지 않은 다른 상황에서도 반환될 수 있습니다. | 올바른 authentication method를 사용 중인지와 자격 증명이 정확한지 확인하세요. |
| 403 | Forbidden | 요청은 이해되었지만 거부되었거나 액세스가 허용되지 않았습니다. 함께 제공되는 오류 메시지에서 이유를 설명합니다. | 사용하려는 엔드포인트에 대한 액세스가 개발자 계정에 포함되어 있는지 확인하세요. App을 허용 목록에 추가해야 할 수도 있습니다(예: Engagement API 또는 Ads API) 또는 액세스를 신청해야 할 수 있습니다. |
| 404 | Not Found | 요청한 URI가 올바르지 않거나 사용자 등 요청한 리소스가 존재하지 않습니다. | 사용 중인 엔드포인트에 대해 유효한 매개변수와 올바른 URI를 사용 중인지 확인하세요. |
| 409 | Connection Exception | 규칙이 없는 필터링된 스트림에 연결을 시도할 때 반환됩니다. | 연결하려는 스트림에 최소 한 개의 규칙을 생성했는지 확인하세요. 필터링된 스트림은 활성 규칙과 일치하는 게시물만 반환합니다. 규칙이 없으면 스트림은 게시물을 반환하지 않습니다. |
| 429 | Too Many Requests | App’s rate limit 또는 Post cap이 소진되어 요청을 처리할 수 없을 때 반환됩니다. Rate Limiting을 참조하세요. | 사용 중인 엔드포인트에서 허용되는 시간 프레임당 요청 수를 확인하세요. 시간 프레임이 재설정될 때까지 기다리세요. 요청을 간격을 두고 보내 요청 한도에 걸리지 않도록 하거나, 다음 사용 가능한 데이터 요금제로 업그레이드하세요. |
| 500 | Internal Server Error | 문제가 발생했습니다. 보통 일시적인 오류이며, 예를 들어 높은 부하 상황이거나 엔드포인트에 일시적인 문제가 있는 경우입니다. | X API status page 또는 developer community forum에서 다른 사람이 유사한 문제를 겪고 있는지 확인하거나, 잠시 기다렸다가 다시 시도하세요. |
| 501 | Unimplemented | X API가 이 엔드포인트를 지원하지 않아 요청을 처리할 수 없습니다. | |
| 503 | Service Unavailable | X 서버는 실행 중이나 요청이 과부하 상태입니다. 나중에 다시 시도하세요. | X API status page 또는 developer community forum에서 다른 사람이 유사한 문제를 겪고 있는지 확인하거나, 잠시 기다렸다가 다시 시도하세요. |
부분 오류
오류 정보
| 제목 | 유형 | 설명 |
|---|---|---|
| 일반 문제 | about:blank | HTTP 상태 코드가 제공하는 정보 외에 추가 정보가 없는 일반적인 문제입니다. |
| 잘못된 요청 문제 | https://api.X.com/2/problems/invalid-request | 이 요청이 유효하지 않음을 나타내는 문제입니다. 요청에 POST 본문이 포함되는 경우, 내용이 올바른 JSON이며 OpenAPI 사양에 부합하는지 확인하세요. |
| 리소스를 찾을 수 없음 문제 | https://api.X.com/2/problems/resource-not-found | 지정된 게시물, 사용자 등이 존재하지 않음을 나타내는 문제입니다. |
| 리소스 권한 없음 문제 | https://api.X.com/2/problems/not-authorized-for-resource | 특정 게시물, 사용자 등을 볼 권한이 없음을 나타내는 문제입니다. |
| 클라이언트 금지됨 문제 | https://api.X.com/2/problems/client-forbidden | 클라이언트가 이 요청을 수행하는 것이 금지되었음을 나타내는 문제입니다. |
| 허용되지 않는 리소스 문제 | https://api.X.com/2/problems/disallowed-resource | 요청한 리소스가 이 API의 원칙을 위반함을 나타내는 문제입니다. |
| 지원되지 않는 인증 문제 | https://api.X.com/2/problems/unsupported-authentication | 사용한 인증 방식이 지원되지 않음을 나타내는 문제입니다. |
| 사용량 상한 초과 문제 | https://api.X.com/2/problems/usage-capped | 사용량 상한을 초과했음을 나타내는 문제입니다. |
| 연결 예외 문제 | https://api.X.com/2/problems/streaming-connection | 연결에 문제가 있음을 나타내는 문제입니다. |
| 클라이언트 연결 해제됨 문제 | https://api.X.com/2/problems/client-disconnected | 클라이언트 연결이 끊어졌습니다. |
| 운영상 연결 해제 문제 | https://api.X.com/2/problems/operational-disconnect | 운영상의 이유로 연결이 해제되었습니다. |
| 규칙 상한 문제 | https://api.X.com/2/problems/rule-cap | 규칙의 최대 개수를 초과했습니다. |
| 규칙 길이 문제 | https://api.X.com/2/problems/rule-length | 액세스 수준에 따라 쿼리 또는 규칙에 허용된 최대 문자 수를 초과했습니다. 액세스 수준을 참조하세요. |
| 잘못된 규칙 문제 | https://api.X.com/2/problems/invalid-rules | 제출한 규칙이 유효하지 않습니다. |
| 중복 규칙 문제 | https://api.X.com/2/problems/duplicate-rules | 제출한 규칙이 중복되었습니다. |
문제 해결 팁
코드 디버깅
코드 디버깅
애플리케이션을 개발할 때 가끔 오류나 예기치 않은 문제가 발생하는 것은 자연스러운 일입니다. 아래는 코드를 디버깅하는 데 도움이 되는 몇 가지 팁입니다:문제를 더 작은 단위로 나눠 어디에서 문제가 발생하는지부터 파악하세요. 예를 들어 REST 또는 스트리밍 엔드포인트를 통합하는 경우, 문제는 다음 항목에 있을 수 있습니다:(5) 단계)에 있는지, 아니면 코드 자체(위의 (6)(7) 단계)에 있는지 확인할 수 있습니다.
- 엔드포인트에는 적절한 인증이 필요합니다.
- 엔드포인트에는 유효한 매개변수와 헤더가 필요합니다. 모든 필터링 규칙은 올바른 연산자와 적절한 구문으로 작성되어야 합니다.
- 엔드포인트의 URI가 정확해야 하며, REST 엔드포인트의 경우 올바른 HTTP 메서드를 사용해야 합니다.
- 액세스하려는 데이터나 리소스가 본인에게는 접근 불가일 수 있습니다(예: 비공개 데이터는 인증된 사용자에게만 제공됨).
- 현재 데이터 패키지는 특정 엔드포인트와 특정 요청 한도에만 액세스를 제공합니다. 자세한 내용은 개발자 포털을 확인하세요.
- 코드에서 서드파티 라이브러리를 사용해 엔드포인트를 통합하고 있습니다.
- 코드가 엔드포인트 응답을 정상적으로 파싱해야 합니다.
인증 관련 문제
인증 관련 문제
- 엔드포인트에 필요한 적절한 인증 방법을 사용하고 있는지 확인하세요. 엔드포인트의 API 참조 페이지에서 확인할 수 있습니다.
- 인증 자격 증명이 올바른지 확인하세요. 개발자 대시보드의 Apps 섹션에서(“Details” 아래) 앱의 키와 토큰을 확인하거나 재발급할 수 있습니다.
- 요청에 대해
oauth_nonce,oauth_signature,oauth_timestamp로 OAuth 1.0a 요청을 올바르게 승인했는지 확인하세요. - 문제가 계속되면 OAuth 라이브러리, Postman 또는 Insomnia와 같은 REST 클라이언트, 혹은 xurl 사용을 고려하세요.
요청 한도 및 게시물 상한 문제
요청 한도 및 게시물 상한 문제
특정 엔드포인트의 요청 한도에 도달했거나 게시물 상한에 도달하면 429 오류가 반환될 수 있습니다.특정 ‘Too many requests’ 오류가 반환되면 해당 엔드포인트의 요청 한도에 도달한 것입니다. 즉, 지정된 기간 동안 해당 엔드포인트에 허용된 최대 요청 수를 초과한 것입니다.요청 한도는 앱 수준과 사용자 수준으로 설정됩니다.
- X 앱 수준은 OAuth 2.0 App-Only를 사용할 때 허용되는 요청 수를 의미하며, 요청 한도는 앱 전체에 대해 전역적으로 결정됩니다. 예를 들어, 어떤 메서드가 한도 창당 15건의 요청을 허용한다면, X 앱을 기준으로 창당 15건의 요청을 보낼 수 있습니다. 이 한도는 사용자 수준 한도와는 완전히 별개입니다. 자세한 내용은 OAuth 2.0 App-Only 가이드를 참고하세요.
- 사용자 컨텍스트 수준은 OAuth 1.0a 사용자 컨텍스트 또는 OAuth 2.0 Authorization Code with PKCE를 사용할 때 사용자별 액세스 토큰당 허용되는 요청 수를 의미합니다. 예를 들어, 어떤 메서드가 한도 창당 15건의 요청을 허용한다면, 사용자별 액세스 토큰마다 창당 15건의 요청이 허용됩니다. 사용자의 액세스 토큰을 얻는 방법은 OAuth 1.0a 및 OAuth 2.0 가이드를 참고하세요.
게시물 누락 문제
게시물 누락 문제
엔드포인트가 게시물을 반환할 것으로 예상했으나 반환되지 않았다면 아래 단계를 따르세요.
- 규칙에서 올바른 operators와 syntax를 사용하고 있는지 확인하세요. 올바른 문법을 점검하기 위해 규칙을 더 작은 절로 나누어 보세요.
- 게시물이 생성될 당시 게시물을 보낸 계정이 protected 상태였다면, 요청 시점에 계정이 공개 상태이더라도 게시물은 반환되지 않습니다. 일반적으로 X Advanced Search로 확인할 수 있습니다. X Advanced Search에서 게시물이 표시되지 않는다면, 엔드포인트에서도 반환되지 않을 것으로 가정해야 합니다.
- 게시물이 전송될 때 스트림에 연결되어 있었나요? 게시물 객체의 타임스탬프는 UTC 기준임을 기억하세요. 게시물이 전송될 때 연결이 끊겼다면, 누락된 데이터를 보충하기 위한 복구 및 중복 기능을 확인하세요.
- 게시물이 전송될 때 규칙이 적용 중이었나요? 게시물 객체의 타임스탬프는 UTC 기준임을 기억하세요.
버퍼 가득 참으로 인한 연결 해제 문제
버퍼 가득 참으로 인한 연결 해제 문제
스트림이 당사의 데이터 전송 속도를 따라가지 못하고 App이 스트림에서 데이터를 충분히 빠르게 소비하지 못하는 경우 다음과 같은 오류가 발생할 수 있습니다:당사는 일정 기간 동안 지연된 전송을 허용하며, 각 스트림에 대해 임시 스테이징 버퍼를 보유하고 있습니다. 그러나 해당 기간 내에 따라잡지 못하면 현재 시점에서 다시 연결할 수 있도록 연결 해제를 진행합니다. 전체 버퍼로 인한 연결 해제 시점에 버퍼에 남아 있던 데이터는 손실될 수 있다는 점에 유의하세요.이 문제는 데이터가 급증할 때 발생할 수 있습니다. 일반적으로 처리 프로세스와 분리된 버퍼링 프로세스를 사용하여 데이터를 신속하게 소비할 것을 권장합니다.v1.1 엔드포인트를 사용하는 엔터프라이즈 고객은 이러한 연결 해제를 방지하기 위해 App을 최적화하는 방법을 connection 및 스트리밍 데이터 소비 관련 문서 here, here에서 자세히 확인할 수 있습니다.연결 해제로 인해 놓친 게시물을 복구하기 위한 다양한 도구가 있으며, 아래 목록에 포함되어 있습니다. 다음 도구는 엔터프라이즈 액세스 수준의 v1.1 엔드포인트에서만 사용할 수 있습니다.
- Redundant Connections - 여러 연결을 통해 여러 서버에서 스트림을 소비하여 하나가 해제되더라도 데이터 손실을 방지합니다.
- Replay - 별도의 스트림으로 최근 5일 이내의 데이터를 복구합니다.
- Backfill - 5분 이내 재연결하여 중단한 지점부터 다시 시작합니다.
- Historical PowerTrack - 전체 X 아카이브에서 데이터를 복구합니다.
도움 받기
질문을 게시하기 전에
- X 개발자 문서에서 문제와 관련된 정보를 검색하세요
- 다른 개발자들이 올린 유사한 질문을 커뮤니티 포럼에서 찾아보세요
- 커뮤니티 포럼 가이드를 확인하세요
질문을 게시할 때 다음 정보를 포함해 주세요
- 문제에 대한 설명
- 수행한 API 호출(가능하면 헤더 포함)
- 반환된 X 응답(오류 메시지 포함)
- 기대했던 응답
- 문제 해결을 위해 시도한 단계 목록
- 문제를 재현하는 데 필요한 단계 목록
- 해당되는 경우, 문제가 발생한 기간
- 해당되는 경우, App ID, Post ID 등
- 관련 코드 샘플 또는 스크린샷