You are here

You are here

REST API Response and Error Codes

SpringCM uses standard HTTP response codes along with error objects to communicate the results of a REST API call. Note that there are subsets of codes that are only applicable for certain operations, such as authentication or file downloads.

Success Response Codes

200 - OK: Success response.

201 - Object created: Use this on successful POST request for object creation in the Object API. 

202 - Request accepted for asynchronous processing:  This is the standard response for a POST to the TASK API.  When a 202 is received, the Response object will always have an Href property.  A GET can be done on this URL to find the status of the submitted task.

204 - No Content: This is returned when the server has completed its work, but there is nothing to return to the user. This is used in some delete requests where the object is eliminated from the system.  Note that “soft deletes” such as deleting a document or folder will just move the object to the Trash and therefore return a 200, not a 204.

Download-only Response Codes:

The following codes are only applicable when downloading documents via the Content API.

205 - Partial Content: Only used for downloads to specify that only part of file was sent

406 - Not Acceptable:  Use when not supported accept header requested

416 - Requested Range Not Satisfiable: Only used for downloads if requested for invalid byte range

Authorization/Security Response Codes:

401 - Unauthorized: This will happen if there is an invalid or missing authentication token in a request or is the standard response for an invalid authentication request.

403 - Forbidden:  Used for when user is not authorized to do the operation.   In this case, the server understood the operation request, but the user does not have rights in SpringCM to do this operation.  If the user does not have security to see the object or the object does not exist, a 404 will be returned.

429 Rate Limit Exceeded:  See REST API Rate Limits for more information.

Error Response Codes

400 - Bad Request: The client has sent a request object that the server could not parse.  Often malformed JSON.

404 - Not Found: Use when object does not exists.  This will also be returned in the case where it might exist in SpringCM, but the user does not have access to it based on their security profile.  In this case the error message returned will be "Object does not exist or the user does not have access rights".

422 - Unprocessable entity: This is used for validation errors where the SpringCM application will not accept the request, such as using an invalid character in a document name, etc.  See the validation section for more information.

500 - Internal Server Error: This is returned in the case of an unexpected server.  This is generally not a client issue and indicates a system error that must be addressed by SpringCM.

Error Response Object

In the case where an error response code is returned, the response body will contain the REST API error object.  A sample error object is shown below.

{
  "Error": {
    "HttpStatusCode": 401,
    "UserMessage": "Access Denied",
    "DeveloperMessage": "Access Denied",
    "ErrorCode": 103,
    "ReferenceId": "b797912a-1f4c-4d4c-b832-6febc4e07875"
  }
}

The error object contains the following properties:

  • HttpStatusCode - Identical to the http status code response header
  • UserMessage - A message that would suitable to show the end user for UI based applications, may be the same as the developer message.
  • DeveloperMessage - Technical error information suitable for developer debugging
  • ErrorCode - SpringCM error code that corresponds to the error message.
  • ReferenceId - SpringCM internal code mapped to this particular error instance.  Useful in the case SpringCM support needs to be engaged.

Additionally, when the response is a 422, an array of validation error objects will be returned. Validation errors occur when the request is syntactically correct, however the rules configured in the SpringCM application do not allow the request to be completed. Below is a sample response shown when trying to create a folder with invalid characters in the name. Validation errors can generally be shown to an end user and they can be prompted to make changes and try the request again.

{
  "Error": {
    "HttpStatusCode": 422,
    "UserMessage": "Validation Error",
    "DeveloperMessage": "See the list of validation errors",
    "ErrorCode": 101,
    "ReferenceId": "430df1ca-9756-48e8-a69d-89fd73642d25"
  },
  "ValidationErrors": [
    {
      "PropertyName": "Name",
      "UserMessage": "Names cannot contain the following characters: \\ / : * ? \" < > |",
      "DeveloperMessage": "Names cannot contain the following characters: \\ / : * ? \" < > |",
      "ErrorCode": 1001
    }
  ]
}

The validation error object contains the following properties:

  • PropertyName - This is the property of the object in the request that did not pass validation.
  • UserMessage - A message that would suitable to show the end user for UI based applications, may be the same as the developer message.
  • DeveloperMessage - Technical error information suitable for developer debugging
  • ErrorCode - SpringCM error code that corresponds to validation error message.

SpringCM Error Codes

Below is the list of SpringCM application error codes.  These will be included with any error response along with the UserMessage and DeveloperMessage and should generally be investigated by the programmer.

100 - General Error 
101 - Validation Error 
103 - AccessDenied
104 - Not Found
105 - Failed To Save
106 - Conflict
107 - Invalid Folder Filter
108 - Invalid System Folder
109 - Folder Not Found 
110 - Invalid Sort Property
111 - Search Criteria Missing
112 - Too Many Items Requested 
113 - Parent Folder Required 
114 - Cannot Parse Uid From Uri
115 - Cannot ParseId From Uri
116 - File Data Required
117 - Document Not Found
118 - Manager Not Found
119 - Document Not Yet Available
120 - Uploads Not Allowed
121 - Downloads Not Allowed
122 - Can Not Update Lock On Version
123 - Can Not Update Version
124 - Invalid Page
125 - Not Supported
126 - Workflow Not Found
127 - Share Link Folder Or Document Missing
128 - Can Not View Lock On Version
129 - MultiPart File Without Name
130 - File Too Big
131 - Aborted Completed Workflow
132 - Signaled Completed Workflow
133 - Invalid Filter Property
134 - Required Property Missing
135 - Missing Search Task
136 - Missing Change Security Task
137 - Security ObjecRequired
138 - Invalid Workflow Signal
139 - Missing Document Process Tracking Task
140 - Folder Required
141 - Document Required
142 - Scope Required
143 - Invalid Group Type
144 - Signature Task Not Found
145 - Content Disposition With Filename Required
146 - Unauthorized
147 - Only One Document Allowed For External Review
148 - New External Review Is Not Enabled
149 - External Review Is Not Enabled

Validation Errors

Below is the list of validation error codes.  Validation errors can normally be displayed to an end user to fix their data and resubmit.
1001 - Invalid Name
1002 - Attribute Validation Failed
1003 - Invalid Selection
1004 - Invalid Parameters Or Access Denied
1005 - Attribute Group Does Not Exist
1006 - Attribute Field Does Not Exist
1007 - Invalid Role
1008 - Change Security Allowed Properties
1009 - Invalid Access Type
1010 - Invalid Email
1011 - Invalid Document Href
1012 - Document Is Checked Out
1013 - At Least One Document Required For External Review
1014 - Check Out Permission Denied
1015 - Date Must Be In The Future
1016 - Invalid Sender
1017 - NotOutForExternalReview