Missing authorization header
GET https://app.asana.com/api/1.0/users/me HTTP/1.1HTTP/1.1 401 Not Authorized
{
"errors": [
{
"message": "Not Authorized"
}
]
}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.
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"
}
]
}| Code | Meaning | Description |
|---|---|---|
| 200 | Success | If data was requested, it will be available in the data field at the top level of the response body. |
| 201 | Created (for object creation) |
Its information is available in the data field at the top level of the response body. The API URL where the object can be retrieved is also returned in the Location header of the response. |
| 400 | Bad Request | This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again. |
| 401 | Unauthorized | A valid authentication token was not provided with the request, so the API could not associate a user with the request. This error also occurs if an app makes a request to a workspace that has disabled that particular app. |
| 402 | Payment Required | The request was valid, but the queried object or object mutation specified in the request is only available to premium organizations and workspaces. |
| 403 | Forbidden | The authentication and request syntax was valid but the server is refusing to complete the request. This can happen if you try to read or write to objects or properties that the user does not have access to. |
| 404 | Not Found | Either the request method and path supplied do not specify a known action in the API, or the object specified by the request does not exist. |
| 429 | Too Many Requests | You have exceeded one of the enforced rate limits in the API. See the documentation on rate limiting for more information. |
| 451 | Unavailable For Legal Reasons | This request was blocked for legal reasons, commonly caused by embargoed IP addresses. |
| 500 | Internal Server Error | There was a problem on Asana's end. |
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:
| Example | Description |
|---|---|
| message | project: Missing input Message providing more detail about the error that occurred, if available. |
| phrase | 6 sad squid snuggle softly 500 errors only. A unique error phrase which can be used when contacting developer support to help identify the exact occurrence of the problem in Asana's logs. |
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 /projectsto 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)
To help you retrieve these very large data sets, there are a number of workaround solutions you can take.
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:
- Retrieve all teams in a workspace, then
- Retrieve all projects for each of those teams in multiple queries
- Instead of retrieving all tasks in a project at once, you can:
- Retrieve all sections in a project, then
- Retrieve all tasks in each of those sections in multiple queries
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.