Request

Response

    GraphQL Error Handling

    GraphQL APIs handle errors differently from traditional REST APIs. Understanding this difference is essential for building robust integrations.

    How GraphQL Errors Differ from REST

    Unlike REST APIs that use HTTP status codes to indicate success or failure, GraphQL APIs return HTTP 200 for most responses—even those containing errors. This design allows for partial responses, where some fields succeed while others fail.

    Response TypeWhat It Means
    2XX with data only Request succeeded
    2XX with errors Request failed or partially failed
    4XX Request-level failure (invalid syntax, authentication)
    5XX Server-level failure

    HTTP Status Codes

    StatusDescription
    200 Request processed. Check response body for success or errors.
    400 Invalid request syntax or parameters.
    401 Missing or invalid authentication credentials.
    403 Access denied. May indicate insufficient scopes/permissions or a blocked 2LO request from browser/web-property traffic.
    429 Rate limit exceeded.
    500 Internal server error.

    Note: For authentication errors (401, 403), see Authentication Error Handling for detailed error codes and troubleshooting. For GraphQL Profile, a 403 on 2LO from browser traffic is a separate security control — see Authentication Patterns.

    403 Forbidden — 2LO from browser or web-property traffic

    GraphQL Profile returns HTTP 403 (not a GraphQL errors array) when a 2LO token is used from browser or web-property traffic on POST /unifieduserprofile.

    Typical causes:

    • Calling Profile from browser JavaScript with a 2LO token
    • A BFF or gateway forwarding browser Sec-Fetch-*, Sec-CH-UA, or client Origin headers upstream while using 2LO

    How to fix:

    • Use 3LO for browser-facing GraphQL calls, or
    • Call Profile with 2LO only from your backend and do not forward browser security headers

    Adding OAuth scopes does not resolve this 403. See Authentication Patterns for migration options.

    Understanding the Error Response

    A GraphQL error response contains two main fields:

    {
      "errors": [...],
      "data": {...}
    }
    
    • errors: Array of error objects describing what went wrong
    • data: May be null or contain partial data if some fields succeeded

    Error Object Structure

    Each error in the errors array contains:

    Expand all
    message
    String
    Human-readable description of what went wrong
    locations
    Array
    Line and column in the query where the error occurred
    path
    Array
    Path to the field that caused the error
    extensions
    Object
    Additional error metadata (see below)
    code
    String
    Standard GraphQL error code
    internalCode
    String
    User Profile API error code (format: UP-<SERVICE>-XXX)
    moreInfo
    String
    Link to relevant documentation
    correlationId
    String
    Unique ID for troubleshooting (matches server logs)

    extensions.code Values

    The extensions.code field indicates the category of error. The User Profile API returns the following codes:

    CodeDescriptionTypical Cause
    FIELD_ACCESS_RESTRICTED The requesting token does not have permission to access or modify the specified field. The field returns null in the response. Consumer has insufficient scope for querying or mutating a field.
    BAD_USER_INPUT A required variable is missing or has an invalid type. Malformed variables object in the request (e.g., missing filter.id).
    GRAPHQL_VALIDATION_FAILED The query string is syntactically invalid or references fields/types that don't exist in the schema. Typo in a field name, or querying a field on the wrong type.
    GRAPHQL_VALIDATION_FAILED (query protection) The document exceeded published query protection limits (aliases, depth, complexity, or tokens). Too many aliases in one request, excessive nesting, or oversized query document. Returns extensions.internalCode UP-GQLSEC-001, data: null, and no field-level path (whole operation fails).

    Note: The FIELD_ACCESS_RESTRICTED code is specific to the User Profile API. BAD_USER_INPUT and GRAPHQL_VALIDATION_FAILED are standard GraphQL error codes defined by the GraphQL specification.

    Query limit rejection vs profile-not-found

    Query protection rejections (UP-GQLSEC-001) fail the entire operation with data: null. This differs from profile lookup errors such as UP-CORE-001, which can return partial data with a field-level path.

    {
      "errors": [{
        "message": "Aliases limit of 15 exceeded, found 16. Use at most 15 total aliases per request and split batch lookups across multiple requests.",
        "extensions": {
          "code": "GRAPHQL_VALIDATION_FAILED",
          "internalCode": "UP-GQLSEC-001",
          "moreInfo": "https://aps.autodesk.com/en/docs/profile/v2/developers_guide/error_handling/errorcodes/",
          "correlationId": "1-abc123-def456ghi789"
        }
      }],
      "data": null
    }
    
    Show More

    For /unifieduserprofile, use the same batching guidance: at most 15 total aliases per request, depth 7, complexity 1000, tokens 1000.

    FIELD_ACCESS_RESTRICTED — Query Example

    When a restricted consumer queries a field that requires elevated permissions, the field returns null and an error is included in the errors array. Other fields in the same query still succeed (partial response).

    {
      "errors": [{
        "message": "Field 'webLinks' is not accessible.",
        "path": ["userProfile", "personalInfo", "webLinks"],
        "extensions": {
          "code": "FIELD_ACCESS_RESTRICTED",
          "field": "webLinks",
          "moreInfo": "https://aps.autodesk.com/en/docs/profile/v2/developers_guide/error_handling/errorcodes/",
          "correlationId": "1-abc123-def456ghi789",
          "internalCode": "UP-DEFAULT-001"
        }
      }],
      "data": {
        "userProfile": {
          "personalInfo": {
            "basicInfo": { "firstName": "John", "lastName": "Doe" },
            "webLinks": null
          }
        }
      }
    }
    
    Show More

    FIELD_ACCESS_RESTRICTED — Mutation Input Rejection

    When a restricted consumer includes a disallowed field in a mutation input, the entire mutation is rejected before any data is written.

    {
      "errors": [{
        "message": "Fields not accessible with your current permissions: websiteUrl",
        "path": [ "updateUserProfileV2" ],
        "extensions": {
          "code": "FIELD_ACCESS_RESTRICTED",
          "moreInfo": "https://aps.autodesk.com/en/docs/profile/v2/developers_guide/error_handling/errorcodes/",
          "correlationId": "1-abc123-def456ghi789",
          "internalCode": "UP-DEFAULT-001"
        }
      }],
      "data": {
        "updateUserProfileV2": null
      }
    }
    
    Show More

    FIELD_ACCESS_RESTRICTED — Mutation with Read Restriction

    A mutation can succeed for the allowed input fields, but the response may contain FIELD_ACCESS_RESTRICTED errors for fields the consumer does not have permission to read back. The update is applied to all accessible fields; only the response is gated.

    {
      "errors": [
        {
          "message": "Field 'webLinks' is not accessible.",
          "path": ["updateUserProfileV2", "personalInfo", "webLinks"],
          "extensions": {
            "code": "FIELD_ACCESS_RESTRICTED",
            "field": "webLinks",
            "moreInfo": "https://aps.autodesk.com/en/docs/profile/v2/developers_guide/error_handling/errorcodes/",
            "correlationId": "1-abc123-def456ghi789",
            "internalCode": "UP-DEFAULT-001"
          }
        },
        {
          "message": "Field 'contactInfo' is not accessible.",
          "path": ["updateUserProfileV2", "personalInfo", "contactInfo"],
          "extensions": {
            "code": "FIELD_ACCESS_RESTRICTED",
            "field": "contactInfo",
            "moreInfo": "https://aps.autodesk.com/en/docs/profile/v2/developers_guide/error_handling/errorcodes/",
            "correlationId": "1-abc123-def456ghi789",
            "internalCode": "UP-DEFAULT-001"
          }
        }
      ],
      "data": {
        "updateUserProfileV2": {
          "personalInfo": {
            "basicInfo": {
              "firstName": "John",
              "lastName": "Doe"
            },
            "webLinks": null,
            "professionalInfo": {
              "jobTitle": "Animator"
            },
            "contactInfo": null
          }
        }
      }
    }
    
    Show More

    Example Error Response

    HTTP/1.1 200 OK
    Content-Type: application/json; charset=utf-8
    
    {
      "errors": [{
        "message": "User with specified userId not found in the system.",
        "locations": [{ "line": 2, "column": 4 }],
        "path": ["userProfile"],
        "extensions": {
          "code": "NOT_FOUND",
          "internalCode": "UP-CORE-001",
          "moreInfo": "https://aps.autodesk.com/en/docs/profile/v2/developers_guide/error_handling/errorcodes/",
          "correlationId": "abc123-def456-ghi789"
        }
      }],
      "data": {
        "userProfile": null
      }
    }
    
    Show More

    Handling Partial Success

    GraphQL responses can succeed partially. For example, if you query multiple fields and one fails:

    {
      "errors": [{
        "message": "Error fetching preferences",
        "path": ["userProfile", "preferences"]
      }],
      "data": {
        "userProfile": {
          "userId": "ABC123",
          "personalInfo": { "firstName": "John" },
          "preferences": null
        }
      }
    }
    
    Show More

    In this example, userId and personalInfo succeeded, but preferences failed.

    Best Practice: Always check for the errors array, even when data is present. Handle missing fields gracefully without crashing your application.

    See Also