HTTP status codes

Unfortunately, sometimes requests to the API are not successful. Failures can occur for a wide range of reasons. In all cases, the API should return an HTTP response status code that indicates the nature of the failure (below), with a response body in JSON format containing additional information.

In the event of a server error, the response body will contain an error phrase. These phrases are automatically generated using the node-asana-phrase library and can be used by Asana support to quickly look up the incident that caused the server error.

Examples

Missing authorization header

GET https://app.asana.com/api/1.0/users/me HTTP/1.1

HTTP/1.1 401 Not Authorized
{
  "errors": [
    {
      "message": "Not Authorized"
    }
  ]
}

Bad request parameters

GET https://app.asana.com/api/1.0/tasks HTTP/1.1
Authorization: Bearer <personal_access_token>

HTTP/1.1 400 Bad Request
{
  "errors": [
    {
      "message": "workspace: Missing input"
    }
  ]
}

Asana had a problem

GET https://app.asana.com/api/1.0/users/me HTTP/1.1
Authorization: Bearer <personal_access_token>

HTTP/1.1 500 Server Error
{
  "errors": [
    {
      "message": "Server Error",
      "phrase": "6 sad squid snuggle softly"
    }
  ]
}

In the event of an error, the response body will contain an errors field at the top level. This contains an array of at
least one error object, described below:

API limits

API queries that run on very large result sets – on the order of tens of thousands of items – may have their results truncated even when you use pagination, use a filter on dates, or you don’t have access to all of those objects.

If your query hits this limit – on the last page of results, the API will respond with a 400 error rather than returning additional data. The 400 error will include a message that indicates a truncated data set.

Note that this limit concerns objects of all resource types (projects, tasks, teams, etc.). This limit also applies to:

• Result sets generated by a single (i.e., canonical) API request (e.g., GET /projects to fetch all projects in a workspace), prior to pagination, and following the application of any query filters provided in the request
• Result sets that would otherwise return a very large number of objects, but you only have access to a subset of them (e.g., guest permissions)

Workarounds

To help you retrieve these very large data sets, there are a number of workaround solutions you can take.

Split API requests

In most cases, you can break down your query into multiple canonical requests based on the hierarchical structure of the object you’re querying. For example:

• Instead of retrieving all projects in a workspace at once, you can:
  1. Retrieve all teams in a workspace, then
  2. Retrieve all projects for each of those teams in multiple queries
• Instead of retrieving all tasks in a project at once, you can:
  1. Retrieve all sections in a project, then
  2. Retrieve all tasks in each of those sections in multiple queries

Export data

If you are unable to use other methods and need an automated export, you can request data using an organization export. This feature is only available to Service Accounts of an Enterprise+ organization.

Additionally, admins can export subsets of organization data as CSV, such as tasks in a project.