Error Handling
This topic explains how the Team Admin API reports errors and how to react to them. Read it when you build error handling into an integration, or when a request fails and you want to know why.
Error formats
An error response uses one of two formats. Check both the HTTP status code and the Content-Type header to find out which one you received.
| Content type | Format | Used for |
|---|---|---|
application/problem+json |
Problem Details | Most errors from the API. |
application/json |
APS error | Some 401, 403, and 404 errors. |
Problem Details
A Problem Details error follows the format in RFC 9457. For example:
{
"type": "https://developer.api.autodesk.com/problems/invalid-request",
"title": "Invalid request",
"status": 400,
"detail": "The request could not be processed as submitted.",
"requestId": "0989f53a-c50d-4514-a335-4c7f756ae6f5",
"errors": [
{
"field": "limit",
"title": "Invalid value",
"detail": "limit must be an integer between 1 and 100."
}
]
}
| Field | Description |
|---|---|
type |
A stable URI that identifies the problem type. Use it to decide what your code does next. |
title |
A short summary of the problem type. |
status |
The HTTP status code of the response. |
detail |
A human-readable explanation of this occurrence. |
instance |
A reference that identifies the specific occurrence. |
requestId |
The request ID, which you can include in a support request. |
errors |
Field-level problems, when the problem can be traced to specific parts of the request. Each item has a field, a title, and a detail. |
type, title, status, and detail are always present. The other fields appear when they apply.
APS error
An APS error has this shape:
{
"developerMessage": "Token is not provided in the request.",
"moreInfo": "https://aps.autodesk.com/en/docs/oauth/v2/developers_guide/error_handling/",
"errorCode": "AUTH-010"
}
| Field | Description |
|---|---|
developerMessage |
A human-readable explanation of the error. |
moreInfo |
A link to APS error-handling documentation. |
errorCode |
The APS error code. It can be empty. |
An APS error might not include a request ID.
Status codes
Once you know which format you received, the status code tells you what to do. Branch on the HTTP status code first, and then on the Problem Details type or the APS errorCode. Don’t branch on title, detail, or developerMessage. Those messages are for people, and their wording can change.
| Status | What it means | What to do |
|---|---|---|
400 |
The request has invalid or malformed data, for example a parameter, a body field, or a pagination cursor. | Check the errors array when it is present, and the detail. Correct the request and send it again. |
401 |
The access token is missing, invalid, or expired. | Get a new access token and retry. See Authentication and Permissions. |
403 |
The token doesn't hold an accepted scope, or you don't administer the team. The response doesn't reveal whether the team exists. | Check the token's scopes and your role on the team. Don't retry unchanged. |
404 |
The resource wasn't found, or isn't visible to you. | Check the IDs in the path and the body. |
410 |
A pagination cursor has expired. | Restart the list without a cursor. See Pagination. |
422 |
The request is well formed, but it can't be applied to the team. Causes include no seats available in the product pool, an unsupported pool, or only inherited assignments remaining. | Check the request against the team's available seats and assignments. Don't retry unchanged. |
429 |
You exceeded a rate limit. | Wait for the number of seconds in the Retry-After header, and then retry. See Rate Limits. |
500, 502, 504 |
The service had a problem, or a request didn't complete in time. | Retry later, with increasing delays between attempts. For a write, see Retry a write safely. |
503 |
The API is temporarily unavailable. | Wait for the number of seconds in Retry-After when it is present. Otherwise retry later, with increasing delays. For a write, see Retry a write safely. |
Each operation returns a subset of these codes. For the codes of one operation, see the REST API Reference.
Retry a write safely
A 500, 502, 503, or 504 response to a write can mean that the change completed anyway. When you send a write again, expect the following:
- Add Team User: if the user is already on the team, the API returns the existing user and sends no new invitation.
- Assign Product: creating an assignment that already exists leaves the team in the same state, and the response contains the current assignment.
- Unassign Product: if no direct or inherited assignment exists, including when you repeat a successful deletion, the request returns
404. If the user still holds the product through the team or a group after a successful removal, a repeat returns422.
If you prefer to check first, list the users with the email filter, or list the assignments with the userId filter. Assignment changes can take a while to appear in team-wide results, so a list might not show a recent change straight away.
Ask for help
If an error persists, use Get Help on the APS portal. Get Help requires an Autodesk Developer Network (ADN) membership.
Include:
- the HTTP method and the URL path,
- the response status code,
- the time of the request, and
- the
X-Request-Idresponse header or therequestIdfield, when the response has one.
To match a request with your own logs, you can send your own X-Request-Id request header. It accepts 1 to 128 letters, digits, periods, underscores, or hyphens, and the API returns it in the response. If you omit it or it isn’t valid, the API generates one.
Don’t include access tokens in a support request.
See also
- Rate Limits — Learn the request limits and how to stay within them.
- Authentication and Permissions — Fix
401and403responses. - REST API Reference — Find the responses of each operation.