Service Responses

When an API is invoked, the API MUST provide a response to the request. Depending on the verb being used, the response MAY include a response body.

The following sections provide information and context regarding status codes, verbs, and general behavior that services SHOULD leverage when providing responses to requests.

Successful Responses (2xx)

Successful responses are those where the service has fulfilled the request. Service responses MUST correspond to the behavior considered proper for a service responding to such a request.

Request Verb	Request Description/Content	Response Code	Response Behavior
GET	Requests a resource, using information in the URL to provide context and filtering	200 ”OK”	The service MUST return the resource(s) that corresponds to the request
GET	Requests a resource, using information in the URL to provide context and filtering	206 ”Partial Content”	The service MUST return the partial content that is available, and MUST provide range information for the requester for acquiring the rest of the resource. For the requester to get a valid resource, it MUST continue to query for additional content until the complete resource is fully downloaded. 206 MUST NOT be used when the response is just a subset of a larger set of paginated data (see Pagination / Continuation). In these cases, retrieving more records is optional. The service MUST include Content-Type and Content-Range headers in its response. Valid example: ../users/{userId}/profileImage that returns only the first part of the image. The returned data would not be a valid image without additional requests to retrieve the rest of the image.
POST (create)	Provides the representation of the resource being created	201 ”Created”	If the service has synchronously created a new resource, the service returns 201 and a full representation of the new resource. If the service also returns the URI of the created resource in the HTTP header, it MUST return the URI in the HTTP Location header field. APIs MAY implement mechanisms that allow returning a subset of the full representation (e.g. $select oData System Query option), but the default response MUST be the full representation of the new resource.
POST (create)	Provides the representation of the resource being created	202 ”Accepted”	If the service will create the resource asynchronously , the service returns a 202 along with a “task” reference (likely TRN; actual format TBD) that contains information that the client can use to get the status of the resource being created. It MUST be noted clearly in the API endpoint documentation if the client needs to anticipate receiving 202 responses.
POST (search)		200 ”OK”	The body of the response contains the results of the search
PUT	Provides the updated resource representation that SHOULD update an extant resource, or MUST facilitate the creation of a new resource	200 ”OK”	This code is returned if the resource already existed and was replaced.
PUT	Provides the updated resource representation that SHOULD update an extant resource, or MUST facilitate the creation of a new resource	201 ”Created”	Same as POST - 201 “Created”
PUT	Provides the updated resource representation that SHOULD update an extant resource, or MUST facilitate the creation of a new resource	202 ”Accepted”	Same as POST - 202 “Accepted”
PATCH	Provides the partial updates for the target resource	200 ”OK”	The service MUST return the full resource representation. If any part of the PATCH update fails, the service MUST return an appropriate error code and MUST NOT modify the original resource.
PATCH	Provides the partial updates for the target resource	202 ”Accepted”	See POST - 202 “Accepted” for more information on successful handling. See PATCH - 200 “OK” for how to handle the failure of any update.
DELETE	Deletes the specified resource. MUST not permit bulk or mass deletes.	204 ”No Content”	The service MUST NOT return a body

Redirection Responses (3xx)

Redirection responses indicate that the requester must take further action in order to fulfill the request. Redirection responses are especially useful for maintaining the integrity of resources URLs over time, because service APIs can direct requesters to updated resource URLs instead of issuing Client Error Responses. Trimble APIs SHOULD return 3xx responses when the requested resource is no longer available at the current URL but is available at another URL known to the API.

Request Verb	Request Description/Content	Response Code	Response Behavior
ANY	A resource is requested	307 ”Temporary Redirect”	The server notifies the requester that the requested resource has temporarily moved to a new URL. The service MUST return the redirected resource URL in the HTTP Location header.
ANY	A resource is requested	308 ”Permanent Redirect”	The server notifies the requester that the requested resource has permanently moved to a new URL. The service MUST return the redirected resource URL in the HTTP Location header.

Trimble APIs SHOULD prefer response codes 307 (Temporary Redirect) and 308 (Permanent) over response codes 302 (Moved Temporarily) and 301 (Moved Permanently) respectively to ensure the request’s HTTP verb and body remain unchanged during redirection.

Client Error Responses (4xx)

Client errors are generated when the requester does something wrong, such as submitting an improperly formatted request or trying to access a resource that does not exist. All client error responses MUST return an error document conforming to the Standard Error Payload.

Verb	Error Condition	Response Code	Response Behavior
ANY	The request contains malformed syntax and cannot be understood by the server	400 ”Bad Request”	The service MUST return a response body with a clear, unambiguous description of the error and at least one suggestion for how to correct the error.
ANY	The request lacks valid authentication credentials that the service requires	401 ”Unauthorized”	The service MUST NOT return any information that can be used to compromise credentials or identities.
ANY	The request is valid and acceptable to the service, but it is refusing to fulfill the request. This could be due to an authentication or authorization issue or attempting to execute a prohibited action	403 ”Forbidden”	The service MUST NOT return any information that can be used to compromise credentials or identities.
GET	The requested resource was not found. (see “Use of Status Code 404 - Not Found”)	404 ”Not Found”	The service MUST return a response body with a clear, unambiguous description of the error and at least one suggestion for how to correct the error.
DELETE PATCH	The resource specified was not found.	404 ”Not Found”	The service MUST NOT return a resource representation.
ANY	The verb specified is not applicable for the requested resource	405 ”Method Not Allowed”	The service MUST return a response body with a clear, unambiguous description of the error and at least one suggestion for how to correct the error.
GET PUT PATCH POST	The request specified an Accept header value that cannot be fulfilled by the service	406 ”Not Acceptable”	The service MUST return an informative message in the response body that indicates which formats are acceptable.
ANY	The request cannot be fulfilled due to the current state of the resource	409 ”Conflict”	The service MUST return information related to the nature of the conflict.

Server Error Responses (5xx)

Server errors are generated when server-side processing of a request fails for any reason.

Verb	Error Condition	Response Code	Response Behavior
ANY	Internal Server Error	500	The service MUST return a response body with a clear, unambiguous description of the error and at least one suggestion for how to correct the error.
ANY	Gateway Timeout	504	The service MUST NOT return any information that can be used to compromise credentials or identities.

5xx error responses MUST return an error document conforming to the Standard Error Payload. 5xx error responses MUST further specify ways for the client to take an actionable next step such as linking to a support ticket page for the service or identifying how to contact support.