Status Codes

HTTP Status Code	Description
`200 OK`	The request was successfully completed. For GET requests, the requested information was found and returned in the response. The updates were successfully completed for PUT requests.
`400 Bad Request`	The request couldn't be processed because it includes missing or invalid information, such as an invalid parameter or a missing required value.
`401 Unauthorized`	You aren't authorized to make the request. Your authentication credentials are missing or invalid.
`404 Not Found`	A requested resource doesn't exist. This code usually appears for GET requests, but it can also appear for DELETE requests (when the specified contract or payment profile doesn't exist).
`500 Internal Server Error`	An internal server occurred. Problem in processing the request in API Layer.

In addition to the standard HTTP codes, the ATA REST API returns detailed error messages for error scenarios.

Error Messages

When a REST request fails, you get an HTTP error response. The response includes a 400-level HTTP status code, an application error code, and an error message that describes the problem.

Each error message includes an application error code and a reason for the error, and may contain the resolution where the error occurred.

For example, you submit a GET request to retrieve a vertex with a label filter that has an incorrect Label. Because the parameter is incorrect, the request isn't valid and the vertex retrieval fails.

In response, you receive an HTTP 400 status error with the following error message, which includes a reason for the failure and more error details.

{
    "code": "1001",
    "message": [
        "Invalid vertex label provided"
    ],
    "reason": "[TOP-1001] Invalid vertex label provided : Networkjj",
    "status": "400"
}

In another example, you submit a POST request to create an edge with a non-existing node ID, the edge creation fails with an error message.

In response, you get an HTTP 400 status error with the following error message, which includes a reason for the failure and/or more error details.

{
    "code": "2022",
    "message": [
        "Invalid fromNode provided"
    ],
    "reason": "[TOP-2022] Invalid fromNode : 100000344 provided for the edge.",
    "status": "400"
}

All requests to the ATA REST API are treated as atomic transactions. This means that if any action taken as part of a request fails, the whole request fails, any changes already made are rolled back, and an error message is returned in the response body in JSON format.

For example, you create a physical device associated with a logical device. The POST request for creating the physical device with the relationship to a logical device is a single transaction. If the physical device is successfully created but the relationship fails, the physical device creation is rolled back and you get an error message in response.

Resolving Common Errors

The most common types of error are:

Type of Error	Description	Resolution
Validation errors	A required parameter is missing, a value isn't supported, a value is in an invalid format, or an unexpected parameter was provided.	Fix the invalid data and resubmit the request. The method descriptions in this document or the Swagger indicate which parameters are required for each method, and the error message guides you to the parameter where the error occurred.
Resource not found errors	A node, edge, entity, or reference ID you provided doesn't match anything in the database.	Confirm your node, edge, entity, or reference IDs and resubmit the request. The referenceId must be used with the businessobjectTypeId to find a unique record. These fields are populated from the source system IDs. For example, if you try to retrieve a vertex 15004, but accidentally enter 150004 (and no vertex with ID 150004 exists), you get a 404 error in the response stating that the vertex wasn't found.
Authentication errors	Your user name or password is incorrect.	Confirm your authentication details and resubmit the request.
Internal Server Errors	After input request validation checks are performed in the REST adapter, the API layer processes the request. Errors occurring in the API layer are considered internal server errors. `"reason": "[INV-9000003] Internal Server processing failed"`	Resubmit the request with the appropriate corrections.