Successful responses are indicated with a 200-series HTTP code and a JSON-based payload containing the object(s) requested, created, modified, or deleted along with an expression of the server’s interpretation of your request.
Error responses are served with a non-200-series HTTP code. Different error codes indicate different reasons for an error. The Twitter API attempts to return appropriate HTTP status codes for every request.
Error response structures
Twitter API v2:
The error structure from the Twitter API v2 will always include the JSON object and elements below. The type includes a direct link to the error description on this index page.
Twitter API HTTP status codes
When an error is incurred during a request, detailed information about the error is returned in the response body to aid in diagnosing the problem. A type field, which is a URI, indicates the nature of the problem, while additional fields provide details about the problem. The type, title, and detail fields will always be returned in these bodies (see table below). Any additional fields, as in the example below, will vary depending on the type of the error.
In some cases you may see the errors detailed above in a response that returned a 200 status code. In those cases, the endpoint is designed to return the data that it can, while providing detailed errors about what it could not return.
For example, the Tweets lookup endpoint allows a Twitter developer App to request more than one ID. If some of those Tweets are available, but one of them has been deleted, the available Tweets would be returned in the data field of the response. An additional
errors field would be returned in the payload, indicating which requested Tweet(s) could not be returned. The same format is used as full request errors to make diagnosing issues easier.
Each problem type indicates the nature of the problem encountered. A full list of problems that you can run into can be found in our API specification as well.
The Twitter API attempts to return appropriate HTTP status codes for every request.
See below for machine-parseable error codes.
Debugging your code
When building an application, it’s normal to run into errors or unexpected issues from time to time. Below are some tips for how you can debug your code:
Start by breaking down the issue into smaller parts to identify where the problem lies. For example, if you’re integrating a REST or a streaming endpoint, the issue could lie with any of the following items:
- The endpoint requires proper authentication.
- The endpoint requires valid parameters and headers. Any filtering rules are built using the correct operators and proper syntax.
- The endpoint’s URI must be correct and, in the case of REST endpoints, the correct HTTP method must be used.
- The data or resource you are trying to access is not accessible to you (for example, private data is only available to authenticated users).
- Your current data package gives you access to certain endpoints only and to specific rate limits. Check out your developer portal for more details.
- Your code uses a third-party library to integrate the endpoint in your code.
- Your code needs to successfully parse the endpoint response.
Read the accompanying error message. This should give you a good indication of what the problem is. Use the tables in the error and response codes section for troubleshooting tips specific to each error code.
For REST endpoints, you can use a REST client like Postman or Insomnia to validate steps (1) to (5) above (review our “Getting started with Postman” guide). If the request with the REST client returns a 200 success status code, you can assume that the issue lies with your code or the library that you are using; not with the endpoint request itself.
For streaming endpoints, you can use cURL (a command-line tool for getting or sending requests using the URL syntax) to check if the issue lies with the request to the endpoint (steps (1) to (5) above) or with your code itself (steps (6) to (7) above).
Troubleshooting authentication issues
Check that you are using the proper authentication method required for the endpoint. This can be identified via the endpoint’s API reference page.
Check that your authentication credentials are correct. You can check or regenerate your App keys and tokens in the Apps section of your developer dashboard (under “Details”).
Check that you have properly authorized your OAuth 1.0a request with
oauth_timestamp for your request.
If the issue persists, consider using an OAuth library, a REST client like Postman or Insomnia, or twurl.
Review our guide on authentication for additional information on all of the above.
Troubleshooting rate limiting and Tweet cap issues
A 429 error can deliver if you hit a rate limit for a given endpoint, or if you hit a Tweet cap.
If the specific ‘Too many requests’ error is returned, you hit the endpoint's rate limit. In other words, you've exceeded the maximum number of requests allowed for an endpoint per specified time period.
Note that rate limits are set per-App and per-user levels.
- Twitter App level indicates the number of requests allowed when using OAuth 2.0 App-Only, where rate limits are determined globally for the entire App. For example, if a method allows for 15 requests per rate limit window, then it allows you to make 15 requests per window on behalf of your Twitter App. This limit is considered completely separately from the user-level limit. Read more in our guide on OAuth 2.0 App-Only.
- User-context level indicates the number of requests that can be made per user Access Token when using OAuth 1.0a User Context or OAuth 2.0 Authorization Code with PKCE. For example, if a method allows for 15 requests per rate limit window, then it allows 15 requests per window and per user Access Token. Read more in our guide on how to obtain a user’s Access Tokens with OAuth 1.0a and OAuth 2.0.
Start by checking the rate limits for the endpoint you are using. You can find this information in the endpoint’s API reference page and in the new developer portal dashboard.
In some cases, you may be able to apply for elevated rate limits. For example, if needed, you can apply for elevated POST access - find out more.
Review our documentation for additional information on rate limits, including how to use HTTP headers to track where your App is at for a given rate limit, how to recover from a rate limit 429 error code, and tips to avoid being rate limited in the first place:
If you've received the specific "Usage cap exceeded: Monthly product cap" error, that means you've hit the Tweet cap for your access level. We have plenty of details on what these Tweet caps are on our documentation page.
Troubleshooting missing Tweet issues
Follow the steps below, if you expected a Tweet to be returned, but it wasn’t delivered by the endpoint.
Check your rule to ensure that you are using the correct operators and syntax. Break the rule into smaller clauses to ensure that you are using the correct syntax.
If the account from which the Tweet was sent was protected at the time the Tweet was created, the Tweet won’t be returned - even if the account is public at the time of the request to the endpoint. You can typically check this using Twitter Advanced Search: if a Tweet is not surfaced using the Twitter Advanced Search functionality, you should assume that it won’t be returned by the endpoint.
The following steps apply to streaming endpoints only:
Were you connected to the stream when the Tweet was sent? Remember that the timestamp delivered in the Tweet object indicates time in UTC. If you experienced a disconnect when the Tweet was sent, review the recovery and redundancy features available to backfill any missed data.
Was your rule in place when the Tweet was sent? Remember that the timestamp delivered in the Tweet object indicates time in UTC.
Troubleshooting webhook issues
Code 32 - Could not authenticate you
This error generally means that something is either malformed in the request, headers, authorization, or the URI that you are specifying. This is not an Account Activity API (premium or enterprise) error, it’s an authorization error and Twitter isn’t getting the proper OAuth setup or URI.
Premium - Make sure you have an approved developer account, have established a dev environment for the Account Activity API. You must use the proper environment name and App tokens in your request.
Enterprise - Make sure the consumer keys and access tokens you are using belong to a Twitter App that has been allowlisted for use of Enterprise products. If you don't have your consumer keys and access tokens, or need to allowlist your Twitter App, please reach out to your account manager.
If you are trying to register a webhook, the POST :env_name/webhooks endpoint requires that you replace
:env_name with your environment name in the request. Also, this endpoint requires that you authenticate using OAuth1.0a User Context, meaning that you need to use the consumer keys and access tokens generated by the Twitter App that you selected as your designated dev environment.
If authenticating with OAuth1.0a User Context, make sure you have properly authorized your request with the proper
Make sure that your access tokens have the proper permission level.
When on the 'Keys and tokens' tab in the App section of your developer dashboard, please make sure that your access tokens have the 'Read, write, and direct messages' permission level.
If the tokens' permission level is set to anything less than this, please navigate to the 'Permissions' tab, adjust the access permission to 'Read, write, and direct messages', then regenerate your access tokens and secret from the 'Keys and tokens' tab.
- Make sure that your URI is formed properly. Please keep in mind that
:env_name is case sensitive.
Code 200 - Forbidden
Code 214 - Webhook URI does not meet the requirements.
Code 214 - High latency on CRC GET request. Your webhook should respond in less than 3 seconds.
Code 214 - Non-200 response code during CRC GET request (i.e. 404, 500, etc).
Code 214 - Too many resources already created.
Code 261 - App cannot perform write actions.
The App that you are using with the API does not have the proper permission level set for its access token and access token secret. Please navigate to the 'Keys and tokens' tab on the Twitter Apps dashboard and check the permission levels assigned to your access token and access token secret. If it is set to anything other than 'Read, write and Direct Messages,' then you are going to have to adjust the settings under the 'Permission' tab and regenerate your access token and access token secret to apply the new settings.
Alternatively, you are trying to register a webhook using OAuth 2.0 Bearer Token authentication, which is not supported. Please authenticate with OAuth1.0a User Context instead as noted in the API reference sections for registering a webhook for enterprise Account Activity API and premium Account Activity API.
Troubleshooting full buffer disconnect issues
You may get one of the following errors when your stream is not keeping up with the speed at which we are delivering data and your App isn't consuming the data from the stream fast enough:
This stream has been disconnected because your client was unable to keep up with us.
This stream has been disconnected for operational reasons.
We allow delivery to get behind for a period of time, and we have a temporary staging buffer amount for each stream on our side; but if you don't catch up, we initiate a disconnect to allow you to reconnect at the current point in time. Please note that this may lead to data loss (for data that is within the buffer at the time of the full buffer disconnect).
These can occur around large spikes in data. Generally, we recommend using a buffer process for consuming data quickly that is separate from the processing process.
If you are an enterprise customer using v1.1 endpoints, you can find out more about optimizing your App to prevent disconnects like this in our articles on connection and on consuming streaming data here and here.
There is a range of tools available for retrieving missed Tweets due to a disconnect, including the ones listed below. Note that the following tools are only available with v1.1 endpoints at enterprise level of access.
Redundant Connections - With multiple connections, consume the stream from multiple servers to prevent missed data when one is disconnected.
Replay - Recover data from within the last 5 days using a separate stream.
Backfill - Reconnect within 5 minutes and start from where you left off.
- Historical PowerTrack - Recover data from the entire Twitter archive.
Twitter API error codes
In addition to descriptive error text, error messages contain machine-parseable codes. While the text for an error message may change, the codes will stay the same.
The following table describes the codes which may appear when working with the Twitter API (note that the Ads API and some other resource families may present additional error codes). If an error response is not listed in the table, fall back to examining the HTTP status codes above in order to determine the best way to address the issue. Please also use the above tables for troubleshooting tips for each corresponding HTTP status code.
The Twitter community forum is available for you to ask technical questions about the Twitter developer platform. This is a discussions forum where you will find questions by other developers and technical information on a variety of topics related to using the Twitter API.
We encourage you to join the conversation by responding to questions and engaging in conversations on our forum. Twitter employees are also there to provide support.
Before you post a question
When you post a question, make sure to include the following information
A description of the problem
The API call being made (include headers, if possible)
The Twitter response returned (include any error messages)
What you expected to receive instead
List of steps taken to troubleshoot the issue
List of steps required to reproduce the issue
If relevant, the time frame during which an issue occurred
If relevant, the App ID, Tweet ID, etc.
Any relevant code sample or screenshots
Please only include one topic/question per post.
For feature requests or missing functionality, please use our feedback platform instead.
For Policy-related issues, such as App suspension, please contact Policy support.
For Twitter-related issues, such as login and account support, please use the Twitter Help Desk.