Errors
When a request fails, you get an HTTP status and a JSON body with a code to check and a message you can show.
The shape of an error
json
{
"error": {
"code": "not_found",
"message": "There is no task KQ7D2M9XWLA in this workspace."
}
}Use code to decide what to do. The message is written for people, so show it rather than match on it.
Codes
| Status | Code | When |
|---|---|---|
| 400 | invalid_field | A field is missing or isn't valid. The message names the field. |
| 400 | invalid_filter | A list filter isn't valid, such as an unknown due value. |
| 401 | unauthorized | No token was sent, or it doesn't work anymore. |
| 403 | read_only | A Read only token tried to change something. |
| 403 | forbidden | Your role doesn't allow this in that space. |
| 404 | not_found | No such endpoint, or no such id in the token's workspace. |
| 429 | rate_limited | Too many requests this minute. See Rate limits. |
Not found or not allowed
Spaces you can't see answer 404, the same as ids that don't exist. That way a token never learns what's in a private space it isn't part of.
A 403 with forbidden means you can see the thing but your role can't make that change, like a member renaming someone else's task.
