Request

Response

    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 typeFormatUsed 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."
        }
      ]
    }
    
    Show More
    FieldDescription
    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"
    }
    
    FieldDescription
    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.

    StatusWhat it meansWhat 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 returns 422.

    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-Id response header or the requestId field, 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