Response codes and errors
The X API provides the following response and error codes to help understand and debug in the moment. Use the debugging guide and error index below for additional context.
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 X API attempts to return appropriate HTTP status codes for every request.
X API v2 HTTP status codes
| Code | Text | Description | Troubleshooting tips |
|---|---|---|---|
| 200 | OK | The request was successful! | |
| 400 | Bad Request | The request was invalid or cannot be otherwise served. An accompanying error message will explain further. Requests without authentication or with invalid query parameters are considered invalid and will yield this response. | Double check the format of your JSON query. For example, if your rule contains double-quote characters associated with an exact-match or other operator, you may need to escape them using a backslash to distinguish them from the structure of the JSON format. |
| 401 | Unauthorized | There was a problem authenticating your request. This could be due to missing or incorrect authentication credentials. This may also be returned in other undefined circumstances. | Check that you are using the correct authentication method and that your credentials are correct. |
| 403 | Forbidden | The request is understood, but it has been refused or access is not allowed. An accompanying error message will explain why. | Check that your developer account includes access to the endpoint you’re trying to use. You may also need to get your App allowlisted (e.g. Engagement API or Ads API) or sign up for access. |
| 404 | Not Found | The URI requested is invalid or the resource requested, such as a user, does not exist. | Check that you are using valid parameters and the correct URI for the endpoint you’re using. |
| 409 | Connection Exception | Returned when attempting to connect to a filtered stream that has no rules. | Check that you have created at least one rule on the stream you are connecting to. Filtered stream will only return Posts that match an active rule. If there are no rules, the stream will not return any Posts. |
| 429 | Too Many Requests | Returned when a request cannot be served due to the App’s rate limit or Post cap having been exhausted. See Rate Limiting. | Check the number of requests per timeframe allowed with the endpoint you’re using. Wait for the timeframe to reset. Space out your requests to ensure you don’t hit rate limits or upgrade to the next available data plan. |
| 500 | Internal Server Error | Something is broken. This is usually a temporary error, for example in a high load situation or if an endpoint is temporarily having issues. | Check the X API status page or the developer community forum in case others are having similar issues, or simply wait and try again later. |
| 501 | Unimplemented | The X API does not support this endpoint and cannot fulfill the request. | |
| 503 | Service Unavailable | The X servers are up, but overloaded with requests. Try again later. | Check the X API status page or the developer community forum in case others are having similar issues, or simply wait and try again later. |
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.
Partial errors
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 Posts lookup endpoint allows a X developer App to request more than one ID. If some of those Posts are available, but one of them has been deleted, the available Posts would be returned in the data field of the response. An additional errors field would be returned in the payload, indicating which requested Post(s) could not be returned. The same format is used as full request errors to make diagnosing issues easier.
Error information
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 X API attempts to return appropriate HTTP status codes for every request.
| Title | Type | Description |
|---|---|---|
| Generic Problem | about:blank | A generic problem with no additional information beyond that provided by the HTTP status code. |
| Invalid Request Problem | https://api.X.com/2/problems/invalid-request | A problem that indicates this request is invalid. If your request takes a POST body, ensure the contents is valid JSON and matches the OpenAPI spec. |
| Resource Not Found Problem | https://api.X.com/2/problems/resource-not-found | A problem that indicates that a given Post, User, etc. does not exist. |
| Resource Unauthorized Problem | https://api.X.com/2/problems/not-authorized-for-resource | A problem that indicates you are not allowed to see a particular Post, User, etc. |
| Client Forbidden Problem | https://api.X.com/2/problems/client-forbidden | A problem that indicates your client is forbidden from making this request. |
| Disallowed Resource Problem | https://api.X.com/2/problems/disallowed-resource | A problem that indicates that the resource requested violates the precepts of this API. |
| Unsupported Authentication Problem | https://api.X.com/2/problems/unsupported-authentication | A problem that indicates that the authentication used is not supported. |
| Usage Capped Problem | https://api.X.com/2/problems/usage-capped | A problem that indicates that a usage cap has been exceeded. |
| Connection Exception Problem | https://api.X.com/2/problems/streaming-connection | A problem that indicates something is wrong with the connection. |
| Client Disconnected Problem | https://api.X.com/2/problems/client-disconnected | Your client has gone away. |
| Operational Disconnect Problem | https://api.X.com/2/problems/operational-disconnect | You have been disconnected for operational reasons. |
| Rule Cap Problem | https://api.X.com/2/problems/rule-cap | You have exceeded the maximum number of rules. |
| Rule Length Problem | https://api.X.com/2/problems/rule-length | You have exceeded the maximum number of characters allowed on your query or rule based on your access level. See access levels. |
| Invalid Rules Problem | https://api.X.com/2/problems/invalid-rules | The rule you have submitted is invalid. |
| Duplicate Rules Problem | https://api.X.com/2/problems/duplicate-rules | The rule you have submitted is a duplicate. |
Troubleshooting tips
Debugging your code
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).
Authentication issues
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_nonce,oauth_signature, andoauth_timestampfor your request. - If the issue persists, consider using an OAuth library, a REST client like Postman or Insomnia, or xurl.
Review our guide on authentication for additional information on all of the above.
Rate limiting and Post cap issues
Rate limiting and Post cap issues
A 429 error can deliver if you hit a rate limit for a given endpoint, or if you hit a Post 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.
- X 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 X 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.
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 Post cap for your access level. We have plenty of details on what these Post caps are on our documentation page.
Missing Post issues
Missing Post issues
Follow the steps below, if you expected a Post 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 Post was sent was protected at the time the Post was created, the Post 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 X Advanced Search: if a Post is not surfaced using the X 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 Post was sent? Remember that the timestamp delivered in the Post object indicates time in UTC. If you experienced a disconnect when the Post was sent, review the recovery and redundancy features available to backfill any missed data.
- Was your rule in place when the Post was sent? Remember that the timestamp delivered in the Post object indicates time in UTC.
Full buffer disconnect issues
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:
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 Posts 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 X archive.
Get help
The X community forum is available for you to ask technical questions about the X 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 X API.
We encourage you to join the conversation by responding to questions and engaging in conversations on our forum. X employees are also there to provide support.
Before you post a question
- Search the X developer documentation for information relating to your issue
- Search the community forum for similar questions by other developers
- Review the community forum guidelines
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 X 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, Post ID, etc.
- Any relevant code sample or screenshots
Please only include one topic/question per post.
If you have feature requests or feedback, please submit these through the X Developer Platform Feedback Form.
For Policy-related issues, such as App suspension, please contact Policy support.
For X-related issues, such as login and account support, please use the X Help Desk.