Troubleshooting REST API issues

Edit online

401 error (authentication error)

Possible reason Solution
Wrong URL Make sure you're using real URL of your account, and not <https://restapi.tpondemand.com/>, <https://md5.tpondemand.com/>, or any other URL from the examples
Wrong token Make sure you've copied the token completely, without leaving out any symbols
Mix up of token and personal token Depending what what kind of token you've generated, make sure you're either using token or access_token parameter
SSO is enabled Single Sign-On in Targetprocess - REST API usage

Incomplete result

Possible reason Solution
Lack of paging If you do not specify takeparameter, you'll only get 25 items. Use paging to get up to 1000 items per API call with APIv1 or APIv2.
Some field are empty and you're using APIv2 With APIv2 if the field is empty, it will not be present in the response at all.
You're not specifying which fields you'd like to pull If you do not specify selection criteria (see Partial response (includes and excludes)), only some basic fields be returned in the response. Please make sure to enumerate all the fields that you'd like to get.
Mix up of APIv1 and APIv2 syntax If you make APIv1 query, and you use API2 parameter select, it will be ignored. The same goes for API2 query with APIv1 selector include. Please make sure you're using appropriate the syntax for your API version.
Using < or > in APIv1 filter If you try to combine two conditions with or in APIv1, only the first one will be applied. or in filters is only supported in APIv2.
Pulling two fields with the same name with APIv2 For example: select={id,project.id} It will try to pull two fields - id of the entity, and id of its project - with the same name id Solution is to define a custom name for at least one of them (or both of them): select={entityId:id,project.id} select={id,projectId:project.id} select={entityId:id,projectId:project.id}

500 error (bad request) - for GET requests

Warning: Always double-check the structure of data (field names, object names, collection names, connections between different object) in meta: https://md5.tpondemand.com/api/v1/index/meta
Possible reason Solution
Mix up of APIv1 and APIv2 syntax APIv1 and APIv2 have different syntax. For example, to filter an item by Project in APIv1 we would use where=(project.name eq \"Mobile\"), while in APIv2 it would be where=(project.name=\"Mobile\"). Please make sure you're using appropriate the syntax for your API version.
Using a term instead of the real entity name, e.g trying to pull Portfolio instead of Project (error message: "Property 'Portfolio' does not exist in 'UserStory'.") Make sure you only pull the fields that actually exist in this entity. You should get the name of the field that not exist in the response.
Using invalid quotes (very popular among Mac users) Make sure you're only using ' or \" as quotes, and never ` or any other type of quotes.
Using a complex selector in APIv2 without defining a custom name for it (error message: "Expression is missing an 'as' clause.") Example: select={id,name,Comments.Where(Owner.Kind=\"User\").Max(CreateDate)} Solution: define a custom name select={id,name,lastcommented:Comments.Where(Owner.Kind=\"User\").Max(CreateDate)}
Trying to aggregate an aggregation (reaching for a collection of a collection) Examples: select={effort:UserStories.Sum(Tasks.Sum(Effort))} select={maxdate:UserStories.Max(Tasks.Max(PlannedEndDate))} select={count:UserStories.Sum(Tasks.Count)} Solution: create a custom field and a metric and store the intermediate result there

500 error (bad request) - for POST requests

Warning: 🚧 Always double-check the structure of data (field names, object names, collection names, connections between different object) in meta: https://md5.tpondemand.com/api/v1/index/meta
Possible reason Solution
Using a term instead of the real entity name Make sure you're using real entity type names, and not terms.
Trying to set an object (like EntityState, Release, Project, Team, etc.) using its name (instead of its ID), e.g. EntityState:\"Done\" Always use ID to set an object value: EntityState:{Id:123} If you do not know its ID - make GET API call to put it beforehand."
Using invalid quotes (very popular among Mac users) Use an array to set a collection. Inside this array every value is an object, so it has to be set using its ID: AssignedTeams:[{Team:{Id:123}}]

403 error (not allowed)

Make sure that the user that you're using for Authentication have permission to perform the action that you're trying to do: Roles and Permissions