#1

Similarly to Questions about error response structure, I can’t seem to find much documentation on the structure of error responses for the v2 API.

Rate limits | Twitter Developer seems to indicate that it’s similar to v1 with “code” and “message”, but Twitter API Response Codes & Error Support | Twitter Developer seems to indicate that “errors” itself isn’t even always returned.

Will “errors” always be in the body of a response to a request that errors?
Is it possible for multiple errors to be in the “errors” list?

Is “message” guaranteed to be in each error in “errors”?
What other fields might be there?
From some basic testing, “code” doesn’t seem to be always included and “parameters” is a possible field.

1 Like
Questions about error response structure
#2

Hey @Harmon758

Great questions all around, and sorry for the delayed response and lack of documentation on this subject.

First off, a few direct answers, starting with 400 errors and then progressing to other HTTP errors:

  • All v2 requests that result in a 400 error should include at least one errors object, but I’m verifying this now.
  • It is possible for multiple error objects to be included in 400 responses.
  • The message field will not always be present in 400 responses.

Here is a list of all the fields that can deliver along with a v2 400 error message.

Name Always present? Description
detail Yes A human-readable description of the cause of an error.
title Yes A brief human-readable name for the type of error.
resource_type No tweet, user, etc. The type of resource that produced an error.
type Yes A URI that uniquely identifies this type of error.
section No data, includes, etc. Where the resource that caused the error is in the response.
message No A description of what specifically caused an individual parameter validation to fail. message is present in all validation error responses such as 400 Bad Request, and should include as much information as possible to help debug. The incorrect part of the request (param name or value) is wrapped in square brackets.
parameter(s) No The request parameter that caused the error. The platform can include multiple objects with a parameters property and a message property in order to describe multiple failed parameter validations.
value No The value of the parameter that produced an error.

Here is an example of a 400 error response with multiple different error objects:

  "errors": [
    {
      "parameters": {
        "tweep.fields": [
          "asdf"
        ]
      },
      "message": "The query parameter [tweep.fields] is not one of [id,expansions,tweet.fields,media.fields,poll.fields,place.fields,user.fields]"
    },
    {
      "parameters": {
        "expansions": [
          "asdf"
        ]
      },
      "message": "The `expansions` query parameter value [asdf] is not one of [author_id,referenced_tweets.id,referenced_tweets.id.author_id,entities.mentions.username,attachments.poll_ids,attachments.media_keys,in_reply_to_user_id,geo.place_id]"
    }
  ],
  "title": "Invalid Request",
  "detail": "One or more parameters to your request was invalid.",
  "type": "https://api.twitter.com/2/problems/invalid-request"
}

Beyond 400, here are a few different examples of other errors you should expect from v2:

Not Found, User Suspended, etc

  "errors": {
    "parameter": "username",
    "value": "example_user",
    "resource_type": "user",
    "title": "Not Found Error",
    "detail":  "Could not find user with username: [example_user].",
    "type": "https://api.twitter.com/2/problems/resource-not-found"
  }
}

Authorization Errors (403 Response)

  "errors": {
    "client_id": "XXXXXXX",
    "registration_url": "https://developer.twitter.com/en/docs/projects/overview",
    "required_enrollment": "Academic",
    "reason": "client-not-enrolled",
    "title": "Client Forbidden",
    "detail": "When authenticating requests to the Twitter API v2 endpoints, you must use keys and tokens from a Twitter developer App that is attached to a Project. You can create a project via the developer portal.",
    "type": "https://api.twitter.com/2/problems/client-forbidden"
  }
}

Authorization Errors (401 Response)

Note: Also returned when an App-only Access Token (fka Bearer Token) attempts to access a User-Auth only endpoint

  "errors": {
    "status":401,
    "title":"Unauthorized",
    "type":"about:blank",
    "detail":"Unauthorized"
  }
}

Too Many Requests (429 Response)

  "errors": {
    "status": 429,
    "title": "Too Many Requests",
    "detail": "Too Many Requests",
    "type": "about:blank"
  }
}
2 Likes