1. SuiteCloud Platform
  2. SuiteTalk Web Services
  3. SuiteTalk REST Web Services API Guide
  4. Error Handling and Logging in REST Web Services
  5. Error Handling in REST Web Services

Error Handling in REST Web Services

In REST web services, HTTP status codes are used to inform you about the success or failure of a request. The following status codes are used:

The error messages clarify whether an error occurred in the request URL, the request headers, the query parameters, or the request body. Error messages also provide more information about the cause of errors and provide possible solutions. Error responses contain the following fields.

The following sections show some common errors with their descriptions.

Invalid Login Information

The following error is returned if the request contains an invalid login token.

            {
    "type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",
    "title": "Unauthorized",
    "status": 401,
    "o:errorDetails": [
        {
            "detail": "Invalid login attempt. For more details, see the Login Audit Trail in the NetSuite UI at Setup > Users/Roles > User Management > View Login Audit Trail.",
            "o:errorCode": "INVALID_LOGIN"
        }
    ]
}

Request with an Invalid Body

The following is a POST request https://demo123.suitetalk.api.netsuite.com/services/rest/record/v1/salesOrder with an invalid reference to a sublist item in the request body.

            {
  "entity": { "id": 107 },
  "location": { "id": 1 },
  "item": {
    "items": [
      {
        "item": { "id": 9999 },
        "amount": 1
      }
    ]
  }
}

The request returns the following error with the JSON path o:errorPath pointing to the invalid value.

            {
    "type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1",
    "title": "Bad Request",
    "status": 400,
    "o:errorDetails": [
        {
            "detail": "Error while accessing resource: You have entered an Invalid Field Value 9999 for the following field: item",
            "o:errorCode": "INVALID_CONTENT",
            "o:errorPath": "item.items[0].item"
        }
    ]
}

Request for a Non-existent Record

The request GET https://demo123.suitetalk.api.netsuite.com/services/rest/record/v1/customer/999 returns the following error if the request is for a non-existent customer.

            {
  "type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",
  "title": "Not Found",
  "status": 404,
  "o:errorDetails": [
    {
      "detail": "Record does not exist.",
      "o:errorCode": "NONEXISTENT_ID"
    }
  ]
}

Invalid Request

The request GET https://demo123.suitetalk.api.netsuite.com/services/rest/record/v1/metadata-catalog/customer, salesOrder returns the following error because there is an extra space in the query parameters. The correct request is https://demo123.suitetalk.api.netsuite.com/services/rest/record/v1/metadata-catalog?select=customer,salesOrder.

            {
  "type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",
  "title": "Bad Request",
  "status": 400,
  "o:errorDetails": [
    {
      "detail": "The request could not be understood by the server due to malformed syntax.",
      "o:errorCode": "INVALID_REQUEST"
    }
  ]
}

Exceeded Concurrency Governance Limit

The following error is returned if the request is rejected due to exceeding the limit allowed by concurrency governance. For information about request limits, see Concurrency Governance and Session Management.

If this error occurs, retry sending the request. For information about implementing a retry logic in your code, see Retrying Failed Web Services Requests.

            {
  "type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",
  "title": "Bad Request",
  "status": 429,
  "o:errorCode": "USER_ERROR"
  "o:errorDetails": [
    {
      "detail": "Concurrent request limit exceeded. Request blocked.",
      "o:errorCode": "CONCURRENCY_LIMIT_EXCEEDED"
    }
  ]
}

System Error

The following error is returned if a system error occurs while the request is being processed. If a system error occurs, contact NetSuite Customer Support and refer to the error ID.

            {
    "type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",
    "title": "Internal Server Error",
    "status": 500,
    "o:errorDetails": [
        {
            "detail": "An unexpected error occurred. Error ID: jrgbpyylphhishmmlxyt",
            "o:errorCode": "UNEXPECTED_ERROR"
        }
    ]
}

Request Headers that Modify the Error Behavior

You can use two different request headers to modify the way errors are handled. You must send the headers in the following format:

            POST  https://demo123.suitetalk.api.netsuite.com/services/rest/record/v1/customer
X-NetSuite-PropertyNameValidation: error
{
  ...
}

PropertyNameValidation

The possible values of this request header are ignore, warning, and error. The default value is warning.

This is a behavior for invalid field names in the request body, such as field names with incorrect spelling, or field names that do not exist on the record. Using this header returns an error if the field in the request is invalid, for example, if it does not exist.

Warnings are returned in the response headers.

PropertyValueValidation

The possible values of this request header are: ignore, warning, and error. The default value is error.

This is a behavior for syntax errors in the field values in the request body. This behavior returns an error if any field value is invalid.

For semantic errors (for example, non existing ID) this header is ignored and an error is always returned.

Warnings are returned in the response headers.

Related Topics

General Notices