Error handling

Sage Intacct REST API requests return HTTP status codes. In addition to the HTTP status codes, Sage Intacct REST API errors include a JSON response payload that provides more details about the error and its causes. The following sections of this topic provide complete details and examples.

Successful requests

For successful requests, Sage Intacct REST API returns HTTP 2XX status codes as follows:

Code Description Notes
200 OK The request succeeded.
201 Created A POST operation successfully created a new resource. The response payload contains an href for the new resource.
202 Accepted The server accepted the request and will execute it later.
204 NoContent The server successfully executed the method but returns no response body. A successful DELETE request always returns 204, indicating that the record no longer exists.
207 MultiStatus A bulk request that returns multiple status codes. Note that there are scenarios in which only one status code and message is returned when it is applicable to all records in the request.

Failed requests

For failed requests, Sage Intacct REST API returns HTTP 4XX and 5XX status codes as follows:

Code Description Notes
400 BadRequest Error detected in the request that can be fixed by the client. For example, the request payload has a schema error.
401 Unauthorized OAuth2 is not able to authenticate the login credential.
403 Forbidden The authenticated user does not have sufficient permission to run the operation or to access the target resource.
404 NotFound Specified resource does not exist for GET or PATCH operation.
405 MethodNotAllowed The requested method is not supported for the specified resource, regardless of authentication or authorization.
409 Conflict Two requests from the same user have the same idempotency key or unique key.
422 UnprocessableEntity Business logic or business validation error. The payload conforms to the schema, but the values are not valid.
429 TooManyRequests Bulk size exceeds rate limit or total number of requests sent in a period exceeds given quota.
500 InternalServerError Sage Intacct internal server error. Provide details like supportId or requestId to the Support team for further assistance. See our FAQ to learn how to contact Support.

Error response payload

In addition to the HTTP status in the response header, REST API errors include a response payload that provides the following information:

  • ia::error object - includes:
    • code - REST API error code in the response payload. A subcategory of the HTTP status code, such as invalidKey , invalidRequest , or operationFailed . In some cases, this code may be a gateway error code such as GW-0011 . For more information, see API gateway error responses .
    • message - REST API error message in the payload, such as Version is not supported or Malformed URL .
    • supportId - Intacct support ID in the payload.
    • details - In some cases the error response includes additional details. For example, when multiple errors are detected in one request or when business logic errors are returned.
  • ia::meta object - metadata about the response:
    • totalCount - Total number of operations processed
    • totalSuccess - Number of operations that succeeded
    • totalError - Number of operations that failed

Example error responses

The following shows a REST API example error response for an invalid request :

Copy
Copied
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "ia::error": {
    "code": "invalidRequest",
    "message": "Version is not supported.",
    "supportId": "63avN%7EYPhcEDEPVpw1ywI1oV0iNQAAAAw"
    }
    "ia::meta": {
        "totalCount": 1,
        "totalSuccess": 0,
        "totalError": 1
    }
}

This example shows a REST API error response that includes details in the response payload:

Copy
Copied
HTTP/1.1 422 Bad Request
Content-Type: application/json

{
  "ia::error": {
    "code": "operationFailed",
    "message": "Operation create object HQemployee failed",
    "supportId": "sojLj%7EX2vg0DE3Vop0PJU6UeQVxQAAAEw",
    "details": [
      {
        "code": "BL01001973",
        "message": "Employee Contact info cannot be empty [Support ID: sojLj%7EX2vg0DE3Vop0PJU6UeQVxQAAAEw]"
      }
    ]
  }
}

API gateway error responses

When a REST API request fails due to a gateway error, the code included in the error response payload starts with GW- and ends with 4 numeric values, such as GW-0001.

  • For 4XX errors, the possible error codes are GW-0010 - GW-0042 .
  • For 5XX errors, the possible error codes are GW-0001 - GW-0009 .

The following example shows a REST API error response payload where the returned code is a gateway error:

Copy
Copied
{
  "ia::error": {
    "code": "GW-0011",
    "message": "Invalid Request",
    "details": {
      "requestId": "AC47C2BE:D9EE_63EBC07F.59"
    }
  }
}

For 4XX gateway errors, the following table lists returned codes, messages, and descriptions:
Code Message Description
GW‑0010 API rate limit exceeded Throttle/rate-limit exceeded, no remaining slots.
GW‑0011 Invalid Request This error could be due a tenant not being available or not found, an inactive or invalid sender ID, an inactive or invalid client ID, or an inactive tenant.
GW‑0012 Missing Tenant Data This error is due to a missing tenant in an OAuth request. For example, when the username element is present in an OAuth token request, but its value does not include the tenant.
GW‑0014 Invalid Content Type This error is caused by XML content included in a REST API request.
GW‑0015 Missing Attribute This error is issued when the request payload does not include a required attribute.
GW‑0031 Invalid Token This error is issued when the JWT token cannot be decoded or does not contain required elements.
GW‑0032 Invalid Token Payload This error is issued when the grant_type is invalid or the payload for the token request is not in the attribute-value format.
GW‑0033 Invalid Token Endpoint This error is issued when the /oauth2 endpoint is not one of the supported options.
GW‑0034 Invalid Authorization Header This error is issued when the header value does not start with Bearer.
GW‑0035 Missing Token Payload This error is issued when the body is missing from the OAuth token request.
GW‑0036 Missing User Name This error is issued when the username element is present in the OAuth token request, but its value is missing or empty.
GW‑0037 Missing Client ID This error is issued when the client_id is missing in an OAuth token request.
GW‑0038 Multiple Client IDs This error is issued when there are multiple client_id in an OAuth token request.
GW‑0039 Multiple Usernames This error is issued when the username element is present in an OAuth token request, but more than one key-value is specified.
GW‑0042 Forbidden This error is issued when there is an external IP with an override cookie.

For 5XX gateway errors, the only returned code and message at this time is: GW-0001 Unable to process request. If you receive this error, contact Support for assistance as described in our FAQ.