1. API
  2. REST API
  3. Errors

Errors

The REST API uses conventional HTTP response codes to indicate the success or failure of a request. The codes can be in one of the following ranges:

Your client application needs to handle errors when the request fails. The following table lists common response codes and possible reasons for failing requests. The JSON-encoded response should always include the message property, a string containing a brief message about the status of your request.

HTTP Status Code

Description

Reasons

200 OK

The request was successful.

 

207 Multiple statuses returned

Part of the request was successful, part of the request failed.

Possible reasons include:

  • Some of the requested resources do not exist or access to these resources is denied. For example, if you send a request to delete multiple attachments associated with a receipt, the REST API returns an error if any of the attachments listed are not associated with the receipt but the listed attachments that are associated with the receipt are deleted successfully.

400 Bad Request

The request is unacceptable.

Possible reasons include:

  • The request was improperly formed. For example:

    • The Authorization header was not formatted correctly — See Authentication Errors.

    • For a PUT or POST request, the Content-Type header is incorrect or there is a syntax error in the request body and the REST API cannot interpret the information. In this case the response object contains the following message string: “<ObjectName> deserialization failed”.

    • Parameter error — The pagination or filtering parameters in the request URL are not valid. The limit parameter may be above the maximum allowed, the offset may not be divisible by the page limit, or there may be a problem with the query expression q.

  • A validation error. There is a problem with the object sent in the request body. See Validation Errors.

401 Unauthorized

Authentication error. The response includes a WWW-Authenticate header with information about the error.

The access token is invalid. See Authentication Errors.

403 Forbidden

Permission to perform the request is denied.

The access token does not allow the client application to perform the operation requested on the resource specified in the request. In most cases, this is due to business rules configured for the SuiteProjects Pro account, which may include:

  • Global or Application settings controlled by account administrators or by SuiteProjects Pro Support — The operation is restricted across the entire account.

  • Role permissions, filter sets (default, or specified using filterSetId), or other user privileges — The client application is using the REST API to access SuiteProjects Pro on behalf of a user who does not have the relevant privileges to perform the operation requested.

  • Invalid filter set — The request specifies the filter set to apply using the filterSetId query parameter and the specified filter set does not exist or is not associated with the user on behalf of whom the client application is using the REST API to access SuiteProjects Pro. See Active Filter Set.

404 Not Found

The requested resource does not exist.

Possible reasons include:

  • The requested resource does not exist.

  • A required URL parameter is missing. For example the {id} URL parameter is missing in a GET request, and the resource only supports retrieving a single object.

405 Method Not Allowed

The method is not allowed.

Possible reasons include:

  • The method is not supported for the resource.

  • A required URL parameter is missing. For example the {id} URL parameter is missing in a PUT or DELETE request.

429 Too Many Requests

API limit reached.

One of the API limits set for the account was reached. See API Limits.

500 Internal Server Error

A problem occurred on SuiteProjects Pro’s end.

If system errors persist, please check SuiteProjects Pro system status, or contact SuiteProjects Pro Support.

503 Internal Server Error

The service is temporarily unavailable.

If the problem persists, please check SuiteProjects Pro system status, or contact SuiteProjects Pro Support.
Note:

The REST API returns HTTP status 500 Internal Server Error if you attempt to access a BI Connector resource endpoint with a valid access token and the BI Connector feature is disabled.

Parameter errors

Requests return a 400 Bad Request HTTP response code if there is a problem with one of the query parameters in the request URL. The response JSON object includes the message property only, with an error description.

Examples of parameter error messages:

  • limit parameter above the maximum allowed — The specified query parameter 'limit' is out of bounds. Provide value between 1 and 1000

  • The page offset is not divisible by the page limit — Invalid limit and offset values. The offset must be divisible by the page limit

  • Problem with the query expression q — Filter error: Expected a valid field name, but found 'created AFTER '2020-' instead

Validation Errors

PUT or POST requests return a 400 Bad Request HTTP response code if there is a problem with any key-value pair in the JSON-encoded request body. The response JSON object includes the following properties:

  • message — The message string shows “Invalid data”.

  • errorFields — An object containing the fields with errors as attributes, and for each field an array of objects containing the attributes:

    • type — The type of validation error returned.

    • message — The error message.

The following example shows the response returned if the request attempts to set or update read-only fields.

            HTTP/ 1.1 400 Bad Request
Content-Type: application/json
 
{
  "errorFields": {
    "created": [{
      "type": "read-only-value",
      "message": "Read-only value"
    }],
    "updated": [{
      "type": "read-only-value",
      "message": "Read-only value"
    }]
  },
  "message": "Invalid data"
}

The following table lists the validation error types

Error Type

Description

custom-error

A custom-error type is usually associated to a form script associated with the entity property form in SuiteProjects Pro.

invalid-value

The value is not formatted correctly. For example, if the field data type and format is string($date), the string value must follow the format “yyyy-mm-dd”. If the value in the request is “2020–10”, the response includes an invalid-value error type for this field with the message "Invalid date format".

netsuite-integration-error

A netsuite-integration-error type is returned if the resource is selected for real-time NetSuite integration, and the operation results in an integration error.

permission-error

A permission-error type is returned if the access token does not allow the client application to perform the operation requested for this field due to the form rules or form permissions configured in SuiteProjects Pro.

required-field

The field is required. The object in the request body must contain a value for this field. For more information about required fields, see REST API Endpoint Reference or Generated API Documentation JSON.

read-only-value

The field is read-only. The field cannot be set or updated using the REST API. Hidden fields are read-only. The REST API returns an error if an attribute-value pair for a hidden field is included in a POST or PUT request body. For more information about read-only fields, see REST API Endpoint Reference or Generated API Documentation JSON.

unknown-field

The attribute is not a valid attribute for the object to be created or updated. For more information about valid object attributes, see REST API Endpoint Reference or Generated API Documentation JSON.

Note:

Attribute names are case sensitive and use camelCase, a naming convention in which each word within a compound word is capitalized except for the first word. For example, note the initial lowercase t and the uppercase L and I for taxLocationId.

unknown-type

Unknown error type.
Note:

An evaluation order is used for the different validation rules. If an error of a given type is encountered, validation stops and a response returned with that given error type. For example, if the object in the request body includes an invalid attribute name, and an attribute-value pair for a read-only field, the unknown-field validation rule is evaluated first, and an error response is returned before the read-only-value validation rule is evaluated.