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 Type | What 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
| Status | Description |
|---|---|
| 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 clientOriginheaders 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
nullor contain partial data if some fields succeeded
Error Object Structure
Each error in the errors array contains:
messageString | Human-readable description of what went wrong |
locationsArray | Line and column in the query where the error occurred |
pathArray | Path to the field that caused the error |
extensionsObject | 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:
| Code | Description | Typical 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_RESTRICTEDcode is specific to the User Profile API.BAD_USER_INPUTandGRAPHQL_VALIDATION_FAILEDare 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
}
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
}
}
}
}
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
}
}
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
}
}
}
}
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
}
}
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
}
}
}
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
- Authentication Patterns - 2LO vs 3LO and browser traffic restrictions
- Error Codes Reference - Complete list of User Profile API error codes
- Rate Limits - Avoid 429 errors
- Authentication Error Handling - OAuth authentication errors