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:

2xx status codes are used for successful requests.
4xx status codes are used for failures due to user error.
5xx status codes are used for failures due to system error.

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.

status – the HTTP status code.
o:errorDetails – an array with error details. One error response can contain multiple error details.
- detail – human–readable error description.
- o:errorCode – the error category in a machine-friendly format.
- o:errorPath (optional) – a machine-readable JSON path that points to the request body where the error occurred.
- o:urlPath (optional) – a machine-readable URI path that points to the part of the URL where the error occurred.
- o:errorHeader (optional) – the machine-friendly name of the request header where the error occurred.
- o:errorQueryParam (optional) – the machine-friendly name of the request query parameter where the error occurred.

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"
        }
    ]
}