Compose HTTP requests and handle errors


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.

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




200 OK

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


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.


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 CRM 2016 and CRM Online

© 2016 Microsoft. All rights reserved. Copyright

Community Additions