Error handling

1. Status codes
2. Missing ability (403)
3. Unknown or forbidden team (404)
4. Invalid query parameters (422)

The API uses standard HTTP status codes. A 2xx response indicates success; the error codes below cover the failures you are most likely to encounter.

#Status codes

Status	Meaning	When it happens
403	Forbidden	Your token is valid but missing the ability required for the endpoint (for example projects:read).
404	Not Found	The team slug is unknown, or you are not a member of that team. Existence is intentionally hidden.
422	Unprocessable Entity	A query parameter is invalid, e.g. per_page above the maximum of 50.

#Missing ability (403)

The token authenticated successfully but does not carry the required read ability.

{
  "message": "This action is unauthorized."
}

Grant the endpoint's ability to your token and retry. The required ability is listed at the top of each resource page.

#Unknown or forbidden team (404)

A 404 is returned both for teams that do not exist and for teams you cannot access. The API does not distinguish between the two, so you cannot probe for the existence of other teams.

{
  "message": "Not found."
}

Check that the {team} segment in the URL is the correct team slug and that your token belongs to a member of that team.

#Invalid query parameters (422)

Validation failures return a 422 with the offending fields under errors.

{
  "message": "The per page must not be greater than 50.",
  "errors": {
    "per_page": [
      "The per page must not be greater than 50."
    ]
  }
}

Review the Response format page for the accepted ranges of per_page and page.