Skip to main content

SmartConnect API Response Message Reference

Updated

SmartConnect API response messages report the outcome of each API call, including errors and per-record status. For request syntax, endpoints, and parameters, see SmartConnect API Endpoints, Parameters, and Function Settings Reference.

IMPORTANT  The SmartConnect API is a legacy API, and the new REST API is intended to replace it. SmartSimple recommends the REST API instead of the SmartConnect API. For more information, see Use REST API.
NOTE  Every message string in this article is shown wrapped in double quotes so that whitespace, including trailing spaces and occasional double spaces, is visible. The double quotes are not part of the response and are used only as delimiters. It is recommended that integrations using exact-string matching preserve all trailing and double spaces. Where possible, use startsWith( ) or contains( ) checks, or trim and normalize whitespace before comparing.

Response Format

All SmartConnect API responses follow this structure:

{
  "message": {
    "error": "",
    "returncode": 200,
    "...": "..."
  }
}

For list and record-update responses, results appear in a records array. Each record carries a status string describing the outcome of that individual operation.

SmartConnect API responses contain the fields described in the following table.

Field Description
error Top-level error message. An empty string means the call as a whole succeeded.
returncode Mirrors the HTTP status. Values greater than 1 are also written to the HTTP response status.
records[*].status Per-record outcome, used when the call processes multiple records.
Payload fields Additional fields such as recordcount, recordindex, recordfrom, recordto, and allcount are added on successful list and read calls.
IMPORTANT  Business-logic errors are returned with HTTP 200 plus a non-empty error field or per-record status. To detect failure, inspect message.error, message.returncode, and records[*].status, not just the HTTP status. Only gateway-level errors such as authentication, throttling, and transport carry non-200 HTTP status codes.

The v1 and v2 endpoints differ in response format as follows:

Aspect v1 v2
Response Content-Type

text/html; charset=UTF-8 

Body is still JSON.

 application/json; charset=UTF-8
Object/record IDs in payload Returned as numeric values Returned as strings.
Per-record status wording Lowercase, informal. For example, "created successfully" Title-case, formal. For example, "Created Successfully ".
Validation error placement Usually in top-level error Usually in per-record status when in batch operation.

↑ Back to top

Gateway and Authentication Messages

These responses are returned before the request reaches a function handler and apply to both v1 and v2.

HTTP 200: Success

A successful SmartConnect API call returns the message in the following table.

Message When
"" as the empty error, with payload fields Operation completed successfully.

↑ Back to top

HTTP 400: Bad Request

HTTP 400 responses return the messages in the following table, along with the condition that triggers each.

Message When
"Invalid credentials or company/alias" Username, password, alias, or root company identifier is missing or invalid.
"Invalid API Token" The API token could not be decoded or is not registered for the company.
"Query parameters are not allowed." Configuration disallows query-string parameters and a query string was present. The Disable Query Parameters in SmartConnect API setting is in the API Settings section of the Integrations tab in Global Settings. This message is returned when that setting is toggled on.
"Request body is empty." Configuration requires a request body and none was provided.
"Invalid URL: URL should start with https://." Request was not made over HTTPS.

↑ Back to top

HTTP 401: Unauthorized

HTTP 401 responses return the messages in the following table, along with the condition that triggers each.

Message When
"Invalid API User Token" The user token in the request header is invalid, expired, or could not be matched to a user.
"No Permission or Invalid Login" Optionally suffixed with " for {username}". The session could not be authenticated, or the user does not have permission.

↑ Back to top

HTTP 405: Method Not Allowed

An HTTP 405 response returns the message in the following table.

Message When
"GET requests are not allowed" GET method has been disabled for the company and a GET request was received. 

↑ Back to top

HTTP 429: Too Many Requests

An HTTP 429 response returns the message in the following table.

Message When
"Number of API Calls within the hour have reached the maximum limit, please try again later" The hourly SmartConnect API call limit for this company has been exceeded.

↑ Back to top

Messages Returned by Both v1 and v2

These messages are returned identically by both endpoint versions with HTTP 200 and a non-empty error field or per-record status.

Permission and Configuration

Both v1 and v2 return the permission and configuration messages in the following table, along with the condition that triggers each.

Message When
"alias error: alias from URL does not match with alias entered in json data" The alias in the URL and the alias in the JSON body do not match.
"Invalid API Request, request is empty or null" The request body is missing or empty.
"You do not have permission to use this API function." The API user does not have the role required by the configured function.
"Service (object:{level}, action:{action}) not implemented" No handler exists for the specified object type and action combination.
"Recordset does not exist" The recordset parameter does not match any configured recordset.
"Invalid SmartConnect Setting" The SmartConnect function configuration is malformed.
"Requested list does not have field list defined" The function exists but its field list is empty.
"Field List is empty" The action requires a field list, but none was configured.
"Consumer Provider link not configured in SmartConnect API settings" A provider-consumer association function is not properly configured.

↑ Back to top

Input Validation

Both v1 and v2 return the input validation messages in the following table, along with the condition that triggers each.

Message When
"Invalid record id" The supplied record ID is invalid.
"Requested field (id={fieldid}) does not match with the object type ({level})" The supplied field belongs to a different object type.
"Requested field not found (id={fieldid})" The supplied field ID does not exist.
"Search keywords can not be empty" A search action was called with an empty keyword string.
"Requested record does not exist (id={recordid})" The specific record could not be found.
"Requested record does not exist" The requested record could not be found. 
"No Application ID was provided" A universal tracking application (UTA)/module action was called without an appid parameter.
"Object type error for Address types" An address operation was called with an incompatible object type.
"Object Type not implemented." The supplied object type is not supported by the notes and attachment endpoint.
"Invalid Object ID and Object Type combination." The object ID does not exist for the specified object type.
"No content or empty content argument provided." A notes or attachment call is missing the content argument.
"No objectid argument provided." A notes or attachment call is missing the objectid argument.
"No object type argument provided." A notes or attachment call is missing the objecttype argument.
"Update Failed.  Maximum 3 identifier fields allowed" Note the two spaces after Failed. An update used more than three identifier fields.
"Update Failed.  Invalid identifier fields" Note the two spaces after Failed. One or more supplied identifier fields are not valid.
"Record exist already" An identifier-based create matched an existing record; no action was taken.

↑ Back to top

Reports

Both v1 and v2 return the report message in the following table.

Message When
"You do not have permission to view this report." The user does not have access to the requested report.

↑ Back to top

Result and Processing

Both v1 and v2 return the result and processing messages in the following table, along with the condition that triggers each.

Message When
"No records" The query returned no rows.
"Too many tables" The query joins more tables than the API allows.
"Encountered error while processing record ({error})" An exception was raised while processing a single record.
"Encountered error while processing list ({error})" An exception was raised while building a list or export.

↑ Back to top

Asynchronous Data Retrieval

Both v1 and v2 return the asynchronous data retrieval messages in the following table, along with the condition that triggers each.

Message When
"Empty data or invalid datatoken" The supplied datatoken for asynchronous fetch is unknown.
"Empty data/session validation failed/time frame to retrieve data has expired/data already retrieved through this endpoint" The asynchronous fetch token has expired, the session is invalid, or the data has already been consumed.

↑ Back to top

Both v1 and v2 return the transaction link operation messages in the following table, along with the condition that triggers each.

Message When
"Update Failed. Invalid link type." The supplied link type is not recognized.
"Update Failed. Object ID not found. " and/or "Update Failed. Transaction ID not found. " Note the trailing space. Required object ID or transaction ID is missing. May appear concatenated, for example "Update Failed. Object ID not found. Transaction ID not found. ".
"Updated Successfully. " Note the trailing space. Transaction link updated.
"Created Successfully. " Note the trailing space. Transaction link created.
"Delete Failed. Transaction link to Object not found." The transaction link being deleted does not exist.

↑ Back to top

Messages That Differ Between v1 and v2

Where the same condition produces different wording in v1 and v2, both are shown.

Per-Record Status

These messages are returned in records[*].status.

Condition v1 Status v2 Status
New record created successfully "created successfully" "Created Successfully. " Note the trailing space.
Existing record updated successfully "updated successfully" "Updated Successfully. " Note the trailing space.
Update failed: generic "update fail" "Update Failed. " Note the trailing space.
Create failed: generic, with appended error detail "create fail{errmsg}" "Create Failed. {errmsg}"
Cannot find object during create-or-update of transaction "add/update failed: Cannot find object with ID:{id}" "Update Failed.  Cannot find object with ID:{id}" Note the two spaces after Failed.
Cannot find object during update "update failed: Cannot find object with ID:{id}" "Update Failed.  Cannot find object with ID:{id}" Note the two spaces after Failed.

↑ Back to top

Other Differences Between v1 and v2

The following table shows the conditions where the v1 and v2 responses differ, along with the response each version returns.

Condition v1 Response v2 Response
Object ID missing on delete Top-level error: "Objectid can not be zero" Per-record status: "Objectid can not be zero"
Association level or type missing from function configuration Top-level error: "Association level cannot be zero" Top-level error: "SmartConnect API function configuration error, association type missing from Field List of function"

↑ Back to top

v1-Only Messages

The v1 endpoint returns the message in the following table.

Message When
"Function is only available in API v2 or up" A function that is only supported by v2, for example, certain delete operations,  was called through the v1 endpoint.

↑ Back to top

v2-Only Messages

The v2 endpoint returns the messages in the following table, along with the condition that triggers each.

Message When
"Function has been deprecated, use Update Provider/Consumer in your configuration" A legacy providers/consumers association function was called through v2. Clients should reconfigure to use the Update Provider/Consumer action.
"Delete operation not allowed for object type" A delete was attempted on an object type that does not support deletion through the SmartConnect API. v1 silently ignores this case; v2 reports it explicitly.

↑ Back to top

Association Endpoint Messages

The Association functions exist in both v1 and v2. The v2 implementation is significantly expanded and returns more granular per-record statuses.

v1 Association Messages

The v1 Association endpoint returns HTTP 200. Success is indicated by a success message; failure by an error value.

Outcome Message When
Error "Objectid can not be zero" The object ID is missing or zero.
Error "error adding or updating association" The database write for the association failed.
Success "association added or updated successfully" The association was inserted or updated.
Success "updated custom fields successfully" Custom fields on the association were updated.

↑ Back to top

v2 Association Messages

The v2 Association endpoint returns a records array. Each record carries an individual status string. Many status messages are composed from reusable prefixes, most of which include a trailing space.

v2 Association Message Prefixes

The v2 Association endpoint composes its status messages from the prefixes and error strings in the following table.

Prefix Exact Value
Object ID missing "Object ID not found. " Note the trailing space.
Object ID not in system "Object ID does not exist. " Note the trailing space.
Sub-object ID missing "Sub Object ID not found. " Note the trailing space.
Role missing "Role not found. " Note the trailing space.
Not-found error "Association not found"
Duplicate error "Association with the same role already exists."

v2 Association Success Messages

The v2 Association endpoint returns the messages in the following table when an association is created, updated, or deleted, or when a matching association already exists.

Message When
"Created Successfully. " Note the trailing space. A new association was inserted.
"Updated Successfully. " Note the trailing space. An existing association was updated.
"Association deleted" The association was deleted.
"Association already exists" No action taken; a matching association already exists.

v2 Association Input Validation Messages

The v2 Association endpoint returns the messages in the following table when a required ID, role, or operation flag is missing or invalid.

Message When
"Object ID not found. " Note the trailing space. sf_object_id is missing from the request body.
"Object ID does not exist. " Note the trailing space. The supplied object ID does not match any existing record.
"Sub Object ID not found. " Note the trailing space. The sub-object ID, contact or company being associated, is missing.
"Role not found. " Note the trailing space. The role ID is missing or could not be resolved.
"Association ID cannot be 0" An update was requested without a valid association ID.
"Association object ids not found." A required pair of object IDs is missing from a batch operation.
"isupdate or isdelete is required for recordid: {associationid}" An existing association ID was supplied without an operation flag.

v2 Association Delete Messages

The v2 Association endpoint returns the messages in the following table when an association delete fails.

Message When
"Delete Failed. Association does not exist or does not match criteria." The target association was not found or did not match the supplied filter criteria.
"Delete Failed. Association not found" The supplied association ID does not exist.

v2 Association Update Messages

The v2 Association endpoint returns the messages in the following table when an association update fails.

Message When
"Update Failed. Association does not exist or does not match criteria." The target association was not found or did not match the supplied filter criteria.
"Update Failed. Association not found" The supplied association ID does not exist.
"Update Failed. Association ID not found" The update referenced a missing association ID.
"Update Failed. Association with the same role already exists." The requested role change would duplicate an existing association.
"Update Failed. Association failed role limit check." The update would violate the configured role minimum or maximum.
"Update Failed. " Note the trailing space. A generic update failure, such as a database write error, occurred.

v2 Association Create Messages

The v2 Association endpoint returns the messages in the following table when an association create fails.

Message When
"Create Failed.  Association failed role limit check." Note the two spaces after Failed. Creation would exceed the configured role limit.
"Create Failed. Role not found. " Note the trailing space. A required role is missing during creation.
"Failed. Role not found. " Note the trailing space. The role could not be resolved during creation.
"Create Failed. Association with the same role already exists." A duplicate association already exists.
"Create Failed. " Note the trailing space. A generic creation failure occurred.
"Failed" A generic failure with no specific cause resolved.
"Association does not exist or does not match criteria" The supplied criteria did not match an existing association.

↑ Back to top

Quick Reference: Spacing in Message Strings

Several message strings contain trailing spaces or double spaces that are easy to overlook. The table below identifies those strings and the spacing to expect.

String Note
"Update Failed.  Maximum 3 identifier fields allowed" Note the two spaces after Failed.
"Update Failed.  Invalid identifier fields" Note the two spaces after Failed.
"Update Failed.  Cannot find object with ID:{id}" Note the two spaces after Failed.
"Create Failed.  Association failed role limit check." Note the two spaces after Failed.
"Created Successfully. " Note the trailing space.
"Updated Successfully. " Note the trailing space.
"Update Failed. "  Note the trailing space.
"Create Failed. "  Note the trailing space.
"Object ID not found. " Note the trailing space.
"Object ID does not exist. " Note the trailing space.
"Sub Object ID not found. " Note the trailing space.
"Role not found. " Note the trailing space.

It is recommended that integrations use String.startsWith( ) or String.contains( ) checks rather than matching exact strings where possible, or trim and normalize whitespace before comparing.

↑ Back to top

HTTP Status Code Summary

The following table summarizes the HTTP status codes returned by the SmartConnect API and how each is used.

HTTP Status Usage
200 Success, or business-logic error returned in the error field.
400 Bad request: invalid credentials, invalid token, missing or disallowed parameters, or non-HTTPS request.
401 Unauthorized: invalid user token or login.
405 Method not allowed: GET disabled.
429 Hourly SmartConnect API call limit exceeded.

Check message.error, message.returncode, and, for batch operations, records[*].status to determine success or failure, since most business-logic failures are returned with HTTP 200.

↑ Back to top

Helpful Links