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": ""

Each problem type indicates the nature of the problem encountered. Following are the types you may encounter:

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.

Resource Not Found


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.

Resource Unauthorized


This occurs when your client app and/or user are not allowed to see a particular Tweet, User, private metrics on a specific Tweet, etc. This may happen because a user is protected and the user does not follow them, 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.

A full list of problems that you can run into can be found in our API specification as well.

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.

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.