Compose HTTP requests and handle errors


Updated: November 29, 2016

Applies To: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

You interact with the Web API by composing and sending HTTP requests. You need to know how to set the appropriate HTTP headers and handle any errors included in the response.

HTTP requests can apply a variety of different methods. When using the web API you will only use the methods listed in the following table.




Use when retrieving data, including calling functions. The expected Status Code for a successful retrieve is 200 OK.


Use when creating entities or calling actions.


Use when updating entities or performing upsert operations.


Use when deleting entities or individual properties of entities.


Use in limited situations to update individual properties of entities. This method isn’t recommended when updating most entities. You’ll use this when updating model entities.

Although the OData protocol allows for both JSON and ATOM format, the web API only supports JSON. Therefore the following headers can be applied.

Every request should include the Accept header value of application/json, even when no response body is expected. Any error returned in the response will be returned as JSON. While your code should work even if this header isn’t included, we recommend including it as a best practice

The current OData version is 4.0, but future versions may allow for new capabilities. To ensure that there is no ambiguity about the OData version that will be applied to your code at that point in the future, you should always include an explicit statement of the current OData version and the Maximum version to apply in your code. Use both OData-Version and OData-MaxVersion headers set to a value of 4.0.

All HTTP headers should include at least the following headers.

Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

Every request that includes JSON data in the request body must include a Content-Type header with a value of application/json.

Content-Type: application/json

You can use additional headers to enable specific capabilities.

  • To return data on create (POST) or update (PATCH) operations for entities, include the return=representation preference. When this preference is applied to a POST request, a successful response will have status 201 (Created) . For a PATCH request, a successful response will have a status 200 (OK). Without this preference applied, both operations will return status 204 (No Content) to reflect that no data is returned in the body of the response by default.


    This capability was added with December 2016 update for Dynamics 365 (online and on-premises).

  • To return formatted values with a query, include the odata.include-annotations preference set to Microsoft.Dynamics.CRM.formattedvalue using the Prefer header. More information:  Include formatted values

  • You also use the Prefer header with the odata.maxpagesize option to specify how many pages you want to return. More information: Specify the number of entities to return in a page

  • To impersonate another user when the caller has the privileges to do so, add the MSCRMCallerID header with the systemuserid value of the user to impersonate. More information:  Impersonate another user using the Web API.

  • To apply optimistic concurrency, you can apply the If-Match header with an Etag value. More information:  Apply optimistic concurrency.

  • To control whether an upsert operation should actually create or update an entity, you can also use the If-Match and If-None-Match headers. More information:  Upsert an entity.

  • When you execute batch operations, you must apply a number of different headers in the request and with each part sent in the body. More information:  Execute batch operations using the Web API.

Whether an http request succeeds or fails, the response will include a status code. Status codes returned by the Microsoft Dynamics 365 Web API include the following.




200 OK

Expect this when your operation will return data in the response body.


201 Created

Expect this when your entity POST operation succeeds and you have specified the return-representation preference in your request.


This capability was added with December 2016 update for Dynamics 365 (online and on-premises).


204 No Content

Expect this when your operation succeeds but does not return data in the response body.


304 Not Modified

Expect this when testing whether an entity has been modified since it was last retrieved. More information: Conditional retrievals


403 Forbidden

Expect this for the following types of errors:

  • AccessDenied

  • AttributePermissionReadIsMissing

  • AttributePermissionUpdateIsMissingDuringUpdate

  • AttributePrivilegeCreateIsMissing

  • CannotActOnBehalfOfAnotherUser

  • CannotAddOrActonBehalfAnotherUserPrivilege

  • CrmSecurityError

  • InvalidAccessRights

  • PrincipalPrivilegeDenied

  • PrivilegeCreateIsDisabledForOrganization

  • PrivilegeDenied

  • unManagedinvalidprincipal

  • unManagedinvalidprivilegeedepth

Client Error

401 Unauthorized

Expect this for the following types of errors:

  • BadAuthTicket

  • ExpiredAuthTicket

  • InsufficientAuthTicket

  • InvalidAuthTicket

  • InvalidUserAuth

  • MissingCrmAuthenticationToken

  • MissingCrmAuthenticationTokenOrganizationName

  • RequestIsNotAuthenticated

  • TamperedAuthTicket

  • UnauthorizedAccess

  • UnManagedInvalidSecurityPrincipal

Client Error

413 Payload Too Large

Expect this when the request length is too large.

Client Error

400 BadRequest

Expect this when an argument is invalid.

Client Error

404 Not Found

Expect this when the resource doesn’t exist.

Client Error

405 Method Not Allowed

This error occurs for incorrect method and resource combinations. For example, you can’t use DELETE or PATCH on a collection of entities.

Expect this for the following types of errors:

  • CannotDeleteDueToAssociation

  • InvalidOperation

  • NotSupported

Client Error

412 Precondition Failed

Expect this for the following types of errors:

  • ConcurrencyVersionMismatch

  • DuplicateRecord

Client Error

501 Not Implemented

Expect this when some requested operation isnt implemented.

Server Error

503 Service Unavailable

Expect this when the web API service isn’t available.

Server Error

Details about errors are included as JSON in the response. Errors will be in this format.

  "code": "<This code is not related to the http status code and is frequently empty>",
  "message": "<A message describing the error>",
  "innererror": {
   "message": "<A message describing the error, this is frequently the same as the outer message>",
   "type": "Microsoft.Crm.CrmHttpException",
   "stacktrace": "<Details from the server about where the error occurred>"

Microsoft Dynamics 365

© 2016 Microsoft. All rights reserved. Copyright

Community Additions