HTTP Errors

The endpoints we release in Labs will be previews and are likely to change before they are released broadly, so we encourage you to take that into consideration as you build. Before getting started, we encourage you to read more about Twitter Developer Labs.

When a request is successful, you will get a 200 level status code.

When a request fails, it may be for one of the following reasons:

401 Unauthorized

A 401 status code means that there was a problem authenticating your request, such as an invalid consumer key or secret.

403 Forbidden

A 403 status code usually means that you have valid authentication credentials but you are not signed up for Labs, or have not activated any Labs products.

400 Bad Requests

A 400 status code indicates there was a problem with the request such as invalid query parameters.

API Errors

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. The additional fields shown below will vary depending on the type of the error.

An example of an error message you would receive looks something like this:

  "client_id": "16395995",
  "type": "",
  "title": "Client Forbidden",
  "detail": "This request must be made with a registered client. Please create an account and enroll in Labs.",
  "reason": "client-not-enrolled",
  "registration_url": ""

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 GET /tweets endpoint allows an 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 Tweets could not be returned. The same format is used as full request errors to make diagnosing issues easier.

For additional guidance be sure to visit the troubleshooting guide for each endpoint, or let us know via the forums if you need additional support.

General errors

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 following error types can be returned by every endpoint.

General Problem

Type: about:blank

This type is used when there is no additional information beyond that provided by the HTTP status code.

Invalid Request


Invalid request is used to indicate a problem with the parameters you've sent to the endpoint. These are commonly invalid request parameters.

Not Found Error


This error is returned when a given Tweet, User, etc. does not exist. Extra fields in the error indicate the ID of the resource that could not be found.

Authorization Error


This occurs when your client app and/or user are not allowed to see a particular Tweet, private metric on a specific Tweet, etc. This may happen because a user is protected, among other things.

Disallowed Resource


This error is returned when the Tweet requested with the metrics endpoint is either older than 30 days or is a Retweet. Requests of this type are not permitted on this endpoint.

Unsupported Authentication


This error is returned when two-legged OAuth is used instead of 3-legged OAuth. For example, this error is returned if two-legged OAuth is used with the metrics endpoint, which is private at this time.

Client Forbidden


The Client Forbidden problem type indicates your Twitter developer app is forbidden from making this request. Usually this is because the app is not associated with an activated Labs preview.


Filtered stream and Sampled stream

The following errors can be returned by the endpoints in the Filtered Stream or Sampled Stream previews.


Usage cap exceeded


This error applies to Filtered Stream only. This is a connection error and indicates your app cannot connect (or it being disconnected) because it exceeded its usage cap.


Rules cap exceeded


This error applies to Filtered Stream only. Your client can receive this error while submitting new rules. It indicates there are too many rules in the stream. Remove existing rules before submitting.


Too many connections


It applies to both Filtered Stream and Sampled Stream. This is a connection error and indicates another client is already connected to the stream. Your app also can receive this error after disconnecting, then attempting to reconnect to a stream with very low data volume. See Troubleshooting to find solutions to this error.


Operational disconnect


It applies to both Filtered Stream and Sampled Stream. This is a connection error your app can encounter when connected to the stream. It indicates your app is being disconnected for one of the following reasons:

  • Your client cannot keep up with the volume of Tweet it receives.
  • Scheduled maintenance, such as planned system upgrades, bug fixes and improvements.
  • Force disconnect, for example when a client degrades performances and cannot be disconnected by its developers.
  • A system issue or internal error.


Additional resources

  • Get started building with our quick start guides.
  • Check out our API reference to learn more about what’s available.
  • Give feedback on Twitter Developer Labs.
  • Tell us about your experience using the Twitter Developer Labs endpoints by filling out this survey.