SuiteScript 2.x RESTlet Error Handling

Error handling for SuiteScript 2.x RESTlets falls into three categories: Supported http/https success codes, http/https error codes, and SuiteScript errors.

HTTP/HTTPS Success Codes

NetSuite supports one main http success code for RESTlets: 200 OK. This code indicates that the request was executed successfully, but may not necessarily mean that your request worked as you intended. In some cases, a SuiteScript error might also occur and be successfully handled by the RESTlet script. In these cases, the 200 OK code is used and details of the error are described in the response body.

Note:

SuiteScript also supports the 206 Partial Content status code, in some instances. For more information about this status code, see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/206.

HTTP/HTTPS Error Codes

NetSuite supports the following http/https error codes for RESTlets. For more information about these error codes, see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status.

Code	Description
302 Moved Temporarily	Your request went to the wrong NetSuite data center. Review your integration and make sure that it generates the NetSuite RESTlet domain dynamically. For details, see Dynamically Generating a Full URL.
400 Bad Request	The RESTlet request failed with a user error. Any errors encountered at run time that are unhandled return a 400 error. (If the user code catches the error, a status code of 200 OK is returned.) For example, you may receive this error code if you send a get request and include a body in the request (the body is not a supported part of a get request in the http (RFC) standard). For more information about this error code, see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400.
401 Unauthorized	There is no valid NetSuite login session for the RESTlet call.
403 Forbidden	The RESTlet request was sent to an invalid domain.
404 Not Found	The RESTlet called is not at the URL used in the call.
405 Method Not Allowed	The request method used is not valid.
415 Unsupported Media Type	An unsupported Content-Type was specified.
500 Internal Server Error	A non-user error occurred that cannot be recovered from by resubmitting the same request. If this type of error occurs, contact Customer Support to file a case.
503 Service Unavailable	The NetSuite database is offline, or a database connection is not available.

Code

Description

302 Moved Temporarily

Your request went to the wrong NetSuite data center. Review your integration and make sure that it generates the NetSuite RESTlet domain dynamically. For details, see Dynamically Generating a Full URL.

400 Bad Request

The RESTlet request failed with a user error. Any errors encountered at run time that are unhandled return a 400 error. (If the user code catches the error, a status code of 200 OK is returned.)

For example, you may receive this error code if you send a get request and include a body in the request (the body is not a supported part of a get request in the http (RFC) standard). For more information about this error code, see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400.

401 Unauthorized

There is no valid NetSuite login session for the RESTlet call.

403 Forbidden

The RESTlet request was sent to an invalid domain.

404 Not Found

The RESTlet called is not at the URL used in the call.

405 Method Not Allowed

The request method used is not valid.

415 Unsupported Media Type

An unsupported Content-Type was specified.

500 Internal Server Error

A non-user error occurred that cannot be recovered from by resubmitting the same request. If this type of error occurs, contact Customer Support to file a case.

503 Service Unavailable

The NetSuite database is offline, or a database connection is not available.

SuiteScript Error Codes Used by RESTlets

The following SuiteScript errors that can occur when using RESTlets.

Code	Description	Notes
INVALID_LOGIN_ATTEMPT	Invalid login attempt.	This error indicates a problem in an OAuth header. It can be returned when the nonce, consumer key, token, or signature in the OAuth header is invalid.
INVALID_LOGIN_CREDENTIALS	You have entered an invalid email address or account number. Please try again.	This error indicates a problem in an NLAuth header.
INVALID_REQUEST	The request could not be understood by the server due to malformed syntax.	This error is returned because of malformed syntax in an OAuth header. For example, this error can occur when the signature method, version, or timestamp parameter is rejected.
INVALID_RETURN_DATA_FORMAT	You should return {1}.	This error is used if the response data does not match the expected format, as specified by the Content-Type header.
SSS_INVALID_SCRIPTLET_ID	That Suitelet is invalid, disabled, or no longer exists.	If you receive this error, make sure that the URL points to the correct RESTlet script deployment ID.
UNEXPECTED_ERROR	An unexpected error occurred. Error ID: {1}	--
TWO_FA_REQD	Two-Factor Authentication required.	This error indicated that two-factor authentication (2FA) is required for the role, but it is missing.

Code

Description

Notes

INVALID_LOGIN_ATTEMPT

Invalid login attempt.

This error indicates a problem in an OAuth header. It can be returned when the nonce, consumer key, token, or signature in the OAuth header is invalid.

INVALID_LOGIN_CREDENTIALS

You have entered an invalid email address or account number. Please try again.

This error indicates a problem in an NLAuth header.

INVALID_REQUEST

The request could not be understood by the server due to malformed syntax.

This error is returned because of malformed syntax in an OAuth header. For example, this error can occur when the signature method, version, or timestamp parameter is rejected.

INVALID_RETURN_DATA_FORMAT

You should return {1}.

This error is used if the response data does not match the expected format, as specified by the Content-Type header.

SSS_INVALID_SCRIPTLET_ID

That Suitelet is invalid, disabled, or no longer exists.

If you receive this error, make sure that the URL points to the correct RESTlet script deployment ID.

UNEXPECTED_ERROR

An unexpected error occurred. Error ID: {1}

TWO_FA_REQD

Two-Factor Authentication required.

This error indicated that two-factor authentication (2FA) is required for the role, but it is missing.

SuiteScript Error Message Formatting for RESTlets

The following examples illustrate how SuiteScript errors are formatted for each supported Content-Type.

application/json

          {
    "error":
    {
        "code":"SSS_INVALID_SCRIPTLET_ID",
        "message":"That Suitelet is invalid, disabled, or no longer exists."
    }
}

application/xml

          <error>
    <code>SSS_INVALID_SCRIPTLET_ID</code>
    <message>That Suitelet is invalid, disabled, or no longer exists.</message>
</error>

text/plain

          error code: SSS_INVALID_SCRIPTLET_ID
error message: That Suitelet is invalid, disabled, or no longer exists.

HTTP/HTTPS Success Codes

HTTP/HTTPS Error Codes

SuiteScript Error Codes Used by RESTlets

SuiteScript Error Message Formatting for RESTlets

Related Topics