Error Handling
This section provides essential information on handling exceptions and errors in the Manufacturing Data Model API, including HTTP status and OAuth errors.
Error types
The Manufacturing Data Model APIs can return three types of errors and exceptions: HTTP statuses, Manufacturing Data Model API exceptions and errors, and OAuth errors. The error payload response format depends on the service that generated the error.
HTTP status response codes
APS services use the standard HTTP status response codes in the response header to convey the successful or failure of a request. A response in the 2xx error code range indicates successful, while a response in the 4xx range signifies a failure in request handling, typically due to an invalid parameter within the request. A response in the 5xx range typically indicates an internal server error.
For list of HTTP status response codes and their descriptions, see here.
Manufacturing Data Model API exceptions and errors
This section provides the error conventions and the list of errors returned by the Manufacturing Data Model API service. The service that generated the error determines the format of the error payload response.
Error conventions for the Manufacturing Data Model API
The following table shows the convention of the MDM API error object:
message string | Description of the error |
locations string | Location of the object |
path string | This is a list of fields indicating the location of the error. |
extensions string | Extensions mapped to the object. |
correlation_id string | Correlation ID mapped to the object. |
code string | Error code mapped to the object. |
Example of an error response for the MDM API
This code snippet illustrates an error response and its components for the MDM API exceptions and errors. It can help in understanding and resolving errors.
Using Query.folder(projectId: ID!, folderId: ID!) with folderId argument not corresponding to a folder.
{
"errors": [
{
"message": "folderId must correspond to a folder.",
"path": [
"folder"
],
"extensions": {
"correlation_id": "ba3d398e-ff32-44a2-9afa-45220119c501",
"code": "BAD_REQUEST"
}
}
],
"data": {
"folder": null
}
}
List of Manufacturing Data Model API Exceptions and Errors
The following list includes error types and request codes, along with their descriptions and example code snippet.
- BAD_REQUEST
- Error Code:
BAD_REQUEST
- Error Description:
- The client provided a bad GraphQL request.
- The server rejected the request due to a client error.
- Example:
When using
Query.folder(projectId: ID!,folderId: ID!)
where thefolderId
argument doesn’t point to a folder that exists.# Using Query.folder(projectId: ID!, folderId: ID!) with folderId argument not corresponding to a folder. { "errors": [ { "message": "folderId must correspond to a folder.", "path": [ "folder" ], "extensions": { "correlation_id": "ba3d398e-ff32-44a2-9afa-45220119c501", "code": "BAD_REQUEST" } } ], "data": { "folder": null } }
Show More
- Error Code:
- CONFLICT
- Error Code:
CONFLICT
- Error Description:
- The GraphQL request can’t be processed because of a conflict with the current state of the target resource.
- The resource may not be in the expected state (for example, locked) or the processing of the request may result in a conflicting state.
- The client can usually retry later.
- Example:
# This error occurs when a request cannot be completed due to a conflict with the current state of the target resource. { "errors": [ { "message": "Conflict on resource. Please try again later or change parameters.", "path": [ "folder" ], "extensions": { "correlation_id": "ba3d398e-ff32-44a2-9afa-45220119c501", "code": "CONFLICT" } } ], "data": { "folder": null } }
Show More
- Error Code:
- FORBIDDEN
- Error Code:
FORBIDDEN
- Error Description:
- The user does not have access to the requested resources.
- Example:
# This error occurs when the user or client attempts to query a folder without sufficient access rights: { "errors": [{ "message": "You do not have access to requested resources.", "path": [ "folder" ], "extensions": { "correlation_id": "ba3d398e-ff32-44a2-9afa-45220119c501", "code": "FORBIDDEN" } }], "data": { "folder": null } }
Show More
- Error Code:
- GATEWAY_TIMEOUT
- Error Code:
GATEWAY_TIMEOUT
- Error Description:
- The service could not process the request in the allowed time.
- Example:
# This error occurs when the service is processing a complex or resource-intensive query and fails to complete within the allocated time frame: { "errors": [{ "message": "The service took too long to respond. Please try again later.", "path": [ "folders" ], "extensions": { "correlation_id": "ba3d398e-ff32-44a2-9afa-45220119c501", "code": "GATEWAY_TIMEOUT" } }], "data": { "folders": null } } }
Show More
- Error Code:
- INTERNAL_SERVER_ERROR
- Error Code:
INTERNAL_SERVER_ERROR
- Error Description:
- This error message signifies an unhandled error that may be related to any of the possible errors, indicating a problem either with the API or with downstream services.
- You can retry sending the request later and/or reach out to us with their correlation ID.
- Example:
# This error occurs when the server encounters an unexpected condition that prevents it from fulfilling the request: { "errors": [{ "message": "Unknown Internal Server Error. You may contact support with your correlation-id.", "path": [ "folders" ], "extensions": { "correlation_id": "ba3d398e-ff32-44a2-9afa-45220119c501", "code": "INTERNAL_SERVER_ERROR" } }], "data": { "folders": null } } }
Show More
- Error Code:
- NOT_FOUND
- Error Code:
NOT_FOUND
- Error Description:
- The requested resource could not be found, either because it does not exist or has been deleted.
- Example:
# This error occurs when querying a folder that does not exist: { "errors": [ { "message": "Requested resource not found.", "path": [ "folder" ], "extensions": { "correlation_id": "ba3d398e-ff32-44a2-9afa-45220119c501", "code": "NOT_FOUND" } } ], "data": { "folder": null } } }
Show More
- Error Code:
- TOO_MANY_REQUESTS
- Error Code:
TOO_MANY_REQUESTS
- Error Description: - The request is rejected due to reaching its allowed quota. You may wait for a few seconds and then attempt again.
- Example:
# This error occurs when querying a folder with client requests that exceed the allocated quota: { "errors": [ { "message": "Too many requests on downstream service. You may have reached your allowed requests quota. You may try again later.", "path": [ "folder" ], "extensions": { "correlation_id": "ba3d398e-ff32-44a2-9afa-45220119c501", "code": "TOO_MANY_REQUESTS" } } ], "data": { "folder": null } } }
Show More
- Error Code:
- UNAUTHORIZED
- Error Code:
UNAUTHORIZED
- Error Description:
- The server could not authenticate the user or client.
- Most likely, you provided a two-legged OAuth token when it should have been a three-legged OAuth token.
- Example:
# This error occurs when a two-legged OAuth token is used instead of a three-legged OAuth token (excluding project admin features): { "errors": [ { "message": "Your authorization failed. Please verify Bearer Token.", "path": [ "componentVersion" ], "extensions": { "correlation_id": "ba3d398e-ff32-44a2-9afa-45220119c501", "code": "UNAUTHORIZED" } } ], "data": { "componentVersion": null } } }
Show More
- Error Code:
OAuth errors
OAuth, specifically OAuth2, is the open standard used across APS for token-based authentication and authorization.
For OAuth related errors, see here.