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 mainly uses the 200 OK status code for RESTlets. This means the request was successful, but it doesn’t always mean everything worked as you planned. Sometimes, the RESTlet script catches a SuiteScript error but still returns 200 OK—look for error details in the response body.

Note:

SuiteScript sometimes supports the 206 Partial Content status code. To learn more, see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/206.

HTTP/HTTPS Error Codes

NetSuite supports these HTTP/HTTPS error codes for RESTlets. For more on these 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 unhandled runtime errors return a 400. But if your code catches the error, you’ll see a 200 OK instead. For example, you’ll get this error if you send a get request with a body (that’s not allowed by HTTP standards). For details, 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	If a non-user error happens and you can’t fix it by resending the request, 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 unhandled runtime errors return a 400. But if your code catches the error, you’ll see a 200 OK instead.

For example, you’ll get this error if you send a get request with a body (that’s not allowed by HTTP standards). For details, 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

If a non-user error happens and you can’t fix it by resending the request, 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

Here are some SuiteScript errors you might see with RESTlets:

Code	Description	Notes
INVALID_LOGIN_ATTEMPT	Invalid login attempt.	This means there’s a problem in the OAuth header—maybe the nonce, consumer key, token, or signature is invalid.
INVALID_LOGIN_CREDENTIALS	You have entered an invalid email address or account number. Please try again.	This means there’s an issue with the NLAuth header.
INVALID_REQUEST	The request could not be understood by the server due to malformed syntax.	You’ll see this error if the OAuth header has bad syntax—like if the signature method, version, or timestamp parameter isn’t accepted.
INVALID_RETURN_DATA_FORMAT	You should return {1}.	This error pops up if the response data format doesn’t match what’s set by the Content-Type header.
SSS_INVALID_SCRIPTLET_ID	That Suitelet is invalid, disabled, or missing. If you see this error, double-check that your URL points to the right RESTlet deployment ID.	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 means two-factor authentication (2FA) is required for the role, but it’s missing.

Code

Description

Notes

INVALID_LOGIN_ATTEMPT

Invalid login attempt.

This means there’s a problem in the OAuth header—maybe the nonce, consumer key, token, or signature is invalid.

INVALID_LOGIN_CREDENTIALS

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

This means there’s an issue with the NLAuth header.

INVALID_REQUEST

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

You’ll see this error if the OAuth header has bad syntax—like if the signature method, version, or timestamp parameter isn’t accepted.

INVALID_RETURN_DATA_FORMAT

You should return {1}.

This error pops up if the response data format doesn’t match what’s set by the Content-Type header.

SSS_INVALID_SCRIPTLET_ID

That Suitelet is invalid, disabled, or missing. If you see this error, double-check that your URL points to the right RESTlet deployment ID.

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 means two-factor authentication (2FA) is required for the role, but it’s missing.

SuiteScript Error Message Formatting for RESTlets

Here’s how SuiteScript errors look 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