Area: Optimizely Content Delivery API
Applies to versions: 2.9.0 and higher


Recommended reading 

General troubleshooting steps

  • Clear your temporary ASP.net files.
  • For troubleshooting purposes, you can prevent site/IIS caching by setting optimizeCompilations to false under <system.web>.
    <compilation debug="true" targetFramework="4.6.1" optimizeCompilations="false" />​

    After troubleshooting, revert the optimizeCompilations setting by setting it to true as default.

Common errors

404 - ContentNotFound when trying to get content with Content Delivery 

  • Does the 'Content Api Access' role have Read access?
    The Content Delivery API implementation uses a RequiredRole property, and this role is used by the ContentApiController (the one responding to your content requests) to filter your content. If this does not have access to the content, the response will result in a 404 - ContentNotFound. See Setting access.
  • Is the Content Delivery API initialized properly?
    The Content Delivery API uses a constructor injection of the IContentApiOptions implementation, but this only works if there actually is an implementation to inject. There are two extension methods for this on the ServiceConfigurationContext object. See Configuring Content Delivery API options.
  • Do you use the correct Accept-Language header?
    Content Delivery API returns content based on the language passed in the Accept-Language header. The Accept-Language header should be used to specify the locale variant of content that the client prefers (see Mozilla - MDN Web Docs for more information).
    The problem is some browsers, like Chrome for example, automatically adds its preferred language to the Accept-Language header, if the header value is not manually set by the user. In this case, the client should manually pass the Accept-Language header to prevent the browser from adding its own header value.
    If you are using the Content Delivery API in an AJAX application, you can specify/override the Accept-Language header value in your front-end code. See this external blog post for a code sample.

404 Http Error when sending request to Content Delivery endpoints

  • Have you installed both the CMS and the Search packages? 
    In this case, (HttpConfiguration)config.MapHttpAttributeRoutes() is called twice and a 404 error is thrown. See Adding search.
    Also, re-index the site after installing the Search package in case you get a 404.
  • Are you using friendly URLs?
    If you are using configuration handlers in your web.config like in the example below, Content Delivery API friendly URLs will throw a 404. Reverse the order of handlers or try and remove the StaticFileHandler.
    <add name="StaticFileHandler" path="*" verb="*" modules="StaticFileModule,DefaultDocumentModule,DirectoryListingModule" resourceType="Either" requireAccess="Read" />
    <add name="ExtensionlessUrlHandler-Integrated-4.0" path="*." verb="*" type="System.Web.Handlers.TransferRequestHandler" preCondition="integratedMode,runtimeVersionv4.0" />​
    Also note that friendly URLs may not work with simple addresses.

404 Http Error when sending request to /token endpoint in EPiServer.ContentDeliveryApi.OAuth

Make sure you have added the following lines at the bottom in Startup.cs file (see OAuth Configuration).

//// Optimizely Content API Authorization
app.UseContentApiIdentityOAuthAuthorization<ApplicationUserManager<ApplicationUser>, ApplicationUser>(new ContentApiOAuthOptions()
RequireSsl = false

500 Internal Server error when using both Content Delivery API and the Service API

The Service API uses UseServiceApiIdentityTokenAuthorization() and the Content Delivery API uses UseContentApiIdentityOAuthAuthorization(), and both these use the OWIN OAuthAuthorizationServerProvider under the hood. If you register both methods, OWIN will throw an exception because of duplicated OAuth provider.

However, because both APIs use OWIN OAuth middleware, you do not need to register both methods. Use whichever method you prefer and retrieve the token. After that, you should be able to use this token to authenticate with both Service API and Content Delivery API. Make sure that your user has sufficient privileges to access both APIs.

CustomContentDeliveryService is not triggered

The CustomContentDeliveryService only works with Content Delivery API version 2.6.1 and lower. For versions 2.9 and higher, you should implement IContentApiModelFilter and set the base properties to null:

[ServiceConfiguration(typeof(IContentApiModelFilter), Lifecycle = ServiceInstanceScope.Singleton)]
    public class CustomContentApiModelFilter : ContentApiModelFilter<ContentApiModel>
        public override void Filter(ContentApiModel contentApiModel, ConverterContext converterContext)
            // Set the properties to null here 

From version 3, another way is to use the select parameter in the endpoints to filter out properties, see the Content Delivery API SDK. Note: v3 endpoints are still in preview state.

I cannot get my images from my content

Use a property model converter (IPropertyModelConverter) which allows you to customize the output sent to the Content Delivery API. An example can be seen in the Music Festical project. See also Serialization and How to customize API to change data returned to clients.

Do you find this information helpful? Please log in to provide feedback.

Last updated: Mar 24, 2021

Recommended reading