Property Manager API v0 Debugging

This section shows you how to handle various kinds of error responses the Property Manager API generates. In addition to standard HTTP error responses, it discusses how to resolve errors reported in rule trees before you activate a property, and how to deal with errors from variables as they are interpreted on the edge once you activate a property. This section also lists the range of HTTP response codes, provides details for many API-specific error messages along with their likely causes, and reports any known issues remaining in the current API release.

Known Issues

The following known issues may affect your ability to use the Property Manager API:

  • Large rule trees that take more than 5 minutes to validate may time out with a 500 error. As a workaround, try to create smaller configurations targeting smaller sets of hostnames. The less executable logic each configuration contains, the less time it takes to validate it.

  • If you associate PAPI credentials with a user who has access to more than one portal account, attempts to create edge hostnames result in authorization errors.

  • If you create a property within Property Manager with an empty set of hostnames, a GET request to the Property Version Hostnames endpoint results in a 500 error.

  • Some streaming media configurations are not supported. PAPI supports all properties supported by Property Manager.

  • Before using PAPI, any properties that use the older Configuration Manager must first be upgraded to the Property Manager within the Luna portal.

JSON Problems

API endpoints routinely respond with failure codes to a wide range of problems with the integrity of the data you are trying to modify, everything from malformed JSON, to missing fields, to mismatching etags digests. The API returns these error responses in the standard JSON Problem format.

PAPI also serializes problems in some success responses. PAPI allows you to succeed in saving property rule or hostname data in a state that would later fail on activation, but by default it embeds guidance about each problem within the response. Two kinds of problem appear in success responses:

  • An errors array notes any problem that would prevent activation. You need to fix these before activating the property.

  • A warnings array notes less severe issues. You can either modify the data in response, or acknowledge the set of warnings when later activating the property.

For example, when you try to PUT a rule tree that’s missing required origin and cpCode behaviors, a 200 response identifies them as errors:

{
    "accountId": "act_1-1TJZFB",
    "contractId": "ctr_1-1TJZH5",
    "groupId": "grp_15225",
    "propertyId": "prp_173136",
    "propertyVersion": 3,
    "etag": "a9dfe78cf93090516bde891d009eaf57",
    "errors": [
        {
            "type": "/papi/v0/errors/validation.required_behavior",
            "title": "Missing required behavior in default rule",
            "detail": "In order for this property to work correctly behavior Content Provider Code needs to be present in the default section",
            "instance": "/papi/v0/properties/prp_173136/versions/3/rules#err_100",
            "behaviorName": "cpCode"
        },
        {
            "type": "/papi/v0/errors/validation.required_behavior",
            "title": "Missing required behavior in default rule",
            "detail": "In order for this property to work correctly behavior Origin needs to be present in the default section",
            "instance": "/papi/v0/properties/prp_173136/versions/3/rules#err_101",
            "behaviorName": "origin"
        }
    ],
    "rules": {
        "name": "default",
        "options": {
            "is_secure": false
        },
        "children": [
            {
                "name": "Handle /my-path",
                "criteriaMustSatisfy": "all",
                "criteria": [
                    {
                        "name": "wildcard",
                        "value": ["/my-path"]
                    }
                ],
                "behaviors": [
                    {
                        "name": "caching",
                        "behavior": "MAX_AGE",
                        "ttl": "1m"
                    }
                ]
            }
        ]
    }
}

Even though you can save the rule tree, you can’t activate the property until you add the missing behaviors. (See the Rules section for guidance on how to structure rule trees.)

PAPI also allows you the option to skip potentially lengthy validation tests that would result in these errors and warnings. You would still need to address the problems prior to activation, but this option allows you to modify and save data more quickly as a matter of routine throughout your development cycle. See Validation and Activation Time for more information.

Debugging Rule Trees

The API may release a wide range of validation errors based on the content of rule trees, many of which are detailed below. A few unusual error scenarios are unique to PAPI:

  • As discussed in the Resources section, you can freeze the API to use a specific set of behavior and criteria versions. If instead you specify the rule format that uses the latest versions, behaviors and criteria silently update, and may produce errors if their validation requirements change. Other validation errors may remain even when properly updating from one rule format version to another.

  • As discussed in the Rules section, some behaviors and criteria are locked and read-only, and can only be modified with assistance from Akamai Professional Services. You get an error if you try to modify or move them elsewhere within the rule tree.

  • As discussed in the Rules section and detailed in the Behavior and Criteria references, some options may be required depending on the values of others. It is much easier to accidentally omit necessary values in the API than in the Luna interface.

  • Some errors may reference Schema objects, which you can examine to determine each product’s support for behaviors and criteria. They also list the full set of options for each, along with their expected data types. However, schemas do not represent dependencies among options.

Aside from errors, PAPI more often returns a set of warnings after checking your chosen set of behaviors and criteria for identifiable logical inconsistencies. Here is a typical warning, whose errorLocation is a URL fragment that can be interpreted as a JSON Pointer expression to help you locate the problem within the JSON tree you submitted:

"warnings": [
    {
        "type": "https://problems.luna.akamaiapis.net/papi/v0/validation/need_feature",
        "errorLocation": "#/rules/behaviors/5",
        "detail": "`Tiered Distribution` only applies to cacheable
              content, but caching was never turned on."
    }
]

Behaviors such as tieredDistribution and prefreshCache can only operate on cached content on edge servers, so the warning identifies when the caching behavior is not enabled. As another example, the cacheKeyIgnoreCase behavior allows requests for files and query parameters with mixed upper- and lower-case letters to resolve to the same cache key. If you pair that behavior with a criteria that doesn’t also specify a case-insensitive match, the warning alerts you not to apply different behaviors to the same cached object based on random variations in case among incoming requests.

These warnings often identify obvious logical problems, such as exclusive sets of criteria when criteriaMustSatisfy is set to all, or nested criteria that can never execute because they’re logically exclusive with their ancestor rules’ criteria. However, as in all programming environments, no validation mechanism can identify all potential bugs, so you need to carefully step through the code. You can also request text/xml rather than application/json from the Property Versions interface if you would rather look at how a version’s combined set of rules and hostnames translate to the Akamai metadata that is ultimately distributed to edge servers. Contact your Akamai Professional Services representative if you need to better understand the metadata.

NOTE: Like the Luna Control Center portal, the API may require you to acknowledge each warning before you activate a property. Unlike the Luna portal, you can batch-acknowledge all warnings by setting acknowledgeAllWarnings to true on the new activation. Either way, pay careful attention to any warnings you have received before you activate a property version, or your site can experience serious problems.

Debugging Variables

Most problems with rule trees are detected prior to activation, but problems with variables often occur only at runtime, and are thus more challenging to debug.

The most useful way to debug variables is to view their values in session-related response headers for test content on the staging network:

  1. As discussed in the section on Declaring Variables, each variable defined in the default rule features two hidden and sensitive options, and you first need to disable both for any variables you want to inspect.

  2. Activate the property that includes the variables on the staging network.

  3. Once content activates, send a Pragma:akamai-x-get-extracted-values header in your test requests. The response includes X-Akamai-Session-Info headers that reflect the value of each declared variable.

  4. After debugging, re-enable the hidden and sensitive options if necessary before activating to the production network.

Logging variables in session response headers allows you to check their final values after the rule tree executes. To specifically respond to errors as they occur within the rule tree, you can apply variableError criteria as part of a debugging rule after any setVariable that may cause a problem. For example, if you set user variables that extract the contents of a specific header or cookie name, an error results if either item is missing from the request. The following criteria test executes if any errors occur for the specified set of variables:

{
    "name" : "variableError",
    "options" : {
        "variableNames" : "CUSTOM_HEADER CUSTOM_COOKIE"
    }
}

This approach does not allow you to report on the specific error, but you can still fashion appropriate behaviors, especially for use in testing on the staging network. For example, this denies the request and responds with an appropriate error:

{
    "name" : "denyAccess",
    "options" : {
        "enabled" : true,
        "reason" : "missing-required-header-or-cookie"
    }
}

For more details on how variables work within rule trees, see Assigning Variables, or Variables. within the Property Manager portal.

JSON Request Schema

Errors about malformed data typically reference schema objects that describe whichever resource you are trying to interact with. PAPI provides a separate Request Schema interface for these objects that reference specific schema files. For example, the following describes the expected data structure when creating a new edge hostname:

GET /papi/v0/schemas/request/EdgeHostnamesPostRequestV0.json

HTTP Success Codes

The API produces the following range of HTTP success codes:

Code Description
200 The request is successful.
201 The new item was successfully created.
204 The item was successfully removed.
302 The requested item is available at the link provided.

The tables below provide details for many of the errors you may encounter, along with the HTTP status codes they share. (Note that this is not an exhaustive listing, and excludes problems relating to rule trees.) Each problem object’s type member corresponds to items listed in the tables below. Problem types reported in HTTP error responses follow this URL pattern, where the type identifier may include an additional slash character:

https://problems.luna.akamaiapis.net/papi/{version}/{type}

URLs for many problem types included within rule tree and property hostname response objects are formed with an additional validation component:

https://problems.luna.akamaiapis.net/papi/{version}/validation/{type}

HTTP Errors

Code Type Problem
400 http/bad-request The system cannot understand your request, perhaps due to malformed data.
401 http/unauthorized The request requires authentication.
403 http/forbidden The authorization token does not allow access to the resource. For example, the request may specify products not authorized on a contract.
404 http/not-found Unable to locate the requested resource.
405 http/method-not-allowed The specified HTTP method is not supported for this resource.
406 http/not-acceptable The content-type restriction specified by your Accept header is not supported.
412 etag-conflict The Etag you provided does not match the most recent edit. The data has changed since initially accessed. Learn more.
412 http/precondition-failed Preconditions such as If-Match or If-Not-Match are not satisfied. The data has changed since initially accessed. Learn more.
415 http/unsupported-media-type The requested MIME format is not allowed.
500 http/internal-server-error The platform experienced an unknown error.
501 http/not-implemented The platform does not support the requested functionality.

Data Errors

Code Type Problem
400 json-mapping-error Your input could not be validated against the schema, most likely because it is not the expected data type.
400 json-parse-error Your input could not be parsed as JSON. The problem response provides details on the location of the parsing error.
400 json-schema-invalid Your input does not validate against the data’s schema.
400 missing-request-body-field Your request is missing a Body field.
400 missing-required-parameter The request URL is missing a required parameter, which is detailed in the problem response.

Edge Hostname Errors

Code Type Problem
400 edgehostname/bad-suffix The edge hostname’s specified domainSuffix is not allowed. Learn more.
400 edgehostname/not-available The specified edge hostname is not available.
403 edgehostname/create-forbidden The product you assigned to the edge hostname is not included in your contract. Learn more.
429 limit-exceeded.edgehostnames_per_contract You exceeded the limit on the number of edge hostnames for your contract, and must deactivate one before proceeding. Contact your Akamai representative for information on how to increase this limit. Learn more.
500 edgehostname/create-error The platform encountered an unknown error when trying to create the edge hostname.

Property Hostname Errors

Code Type Problem
400 property-version-hostname/bad-cnameto The cnameTo value references an edge hostname that doesn’t exist.
400 property-version-hostname/edgehostname-mismatch You supplied both a cnameTo and edgeHostnameId that reference different hostnames. Learn more.
400 property-version-hostname/missing-cnameto-or-edgehostnameid You need to specify either a cnameTo or a edgeHostnameId member. Learn more.
501 property-version-hostname/unsupported-cnametype You can only specify a property hostname whose cnameType is EDGE_HOSTNAME. Learn more.

An additional set of errors may be listed within Hostname objects that prevent you from activating the property version:

Type Description
generic_behavior_issue.origin_name_hostname_overlap An origin may not specify the same hostname as a property.
hostnames.bad_hostname_format The hostname is not formatted properly.
hostnames.disallowed_akamaihd_dot_net_hostname The AkamaiHD hostname is invalid. The prefix for a.akamaihd.net has a maximum 16 alphanumeric and underscore characters.
hostnames.disallowed_akamaized_dot_net_hostname The hostname may not specify akamaized.net.
hostnames.dualstack_dissuasion_warning Make sure your origin can handle IPv6 traffic.
hostnames.duplicate_hostname The hostname is listed more than once.
hostnames.empty_hostnames Specify at least one property hostname.
hostnames.empty_string_hostname The hostname may not be empty.
hostnames.hostname_contains_underscore Avoid underscore characters in hostnames, which may cause problems for some DNS resolvers.
hostnames.insecure_property_secure_edge_hostname A secure edge hostname is incompatible with your non-secure property.
hostnames.max_hostnames_limit_hard You have reached the maximum number of hostnames per property. Either reconfigure using the instantConfig behavior, split your hostnames across more than one property, or consult with your account representative.
hostnames.max_hostnames_limit_soft You have exceeded the optimal number of hostnames per property. Either reconfigure using the instantConfig behavior, split your hostnames across more than one property, or consult with your account representative.
hostnames.mdc_subdomain_prefix The hostname is formatted incorrectly, and can’t begin with a hyphen.
hostnames.missing_edgehostname A property hostname needs to reference a corresponding edge hostname.
hostnames.secure_property_insecure_edge_hostname An edge hostname is incompatible with your secure property.
hostnames.secure_property_insecure_edge_hostname_shared_cert An edge hostname is incompatible with your secure property.
hostnames.shared_cert_subdomain_prefix The hostname is formatted incorrectly, and can’t begin with a hyphen.
hostnames.unknown_edge_hostname The edge hostname is unavailable, and may not exist.

Property Errors

Code Type Problem
400 property/invalid-name Property names may only use alphanumeric characters, underscores, dashes, and dots.
400 property/name-in-use Each property name must be unique.
403 property-version/lock-error Only Akamai representatives can change read-only behaviors, criteria, and child rules. Learn more.
403 property-version/lock-error/behaviors-changed Read-only behaviors have been added, removed, changed, or moved. Learn more.
403 property-version/lock-error/criteria-changed Read-only criteria have been added, removed, changed, or moved. Learn more.
403 property-version/lock-error/rule-structure-changed Read-only rules have been added, removed, changed, or moved. Learn more.
404 property-deletion/not-found The property you are trying to delete is unknown.
404 property-version/not-found The requested Property version is not available.
429 limit-exceeded.properties_per_contract You exceeded the limit on the number of properties for your contract, and must deactivate one before proceeding. Contact your Akamai representative for information on how to increase this limit. Learn more.
500 property-version/error The platform could not process your request on the specified property version.

Activation Errors

Code Type Problem
400 activation/bad-notifyemails Activations require at least one email address specified in the notifyEmails array. Learn more.
400 activation/missing-compliance-record-info For Akamai representatives activating customers’ properties, nonComplianceReason cannot be NONE without having a valid unitTested, peerReviewedBy, and customerEmail. Either provide those values or change to a different nonComplianceReason.
400 activation/missing-compliance-record Akamai representatives must provide a compliance record before activating a property on customers’ behalf on the production network. For details, see the required schema: /papi/v0/schemas/request/CreateNewActivationRequestV0.json #/properties/complianceRecord.
400 activation/self-peer-review Akamai representatives may not peer review their own activations.
400 activation/warnings-not-acknowledged Before proceeding, you must acknowledge the activation warnings listed in the problem response. Learn more.
403 property-version/already-activated The specified property version has already been activated. To make changes you must first create a new property version.
404 activation-cancellation/not-found The activation you are trying to cancel is unknown. Learn more.
422 activation-cancellation/unprocessable-status The activation is not in a pending state, so it can’t be canceled. Learn more.
422 activation/already-activated The property version has already been activated.
422 activation/still-pending The property version is currently pending activation or deactivation. Please wait until the operation is complete before starting another activation or deactivation.
429 rate-limit-exceeded.activations You made too many activations in the amount of time allowed for your contract. The problem response provides details on when you can request more activations. Learn more.
500 activation-cancellation/cancel-error The platform could not cancel the activation.
500 activation/property_activation_failed The property activation failed.
500 deactivation/property_deactivation_failed The property deactivation failed.

Behavior/Criteria Errors

These general errors relate to how you implement behaviors and criteria. They may be listed within Rule objects, and may prevent you from activating the property version:

Type Description
compatible_behaviors Rules include incompatible behaviors.
condition_no_prompt_upgrade You must upgrade to a new version of a criteria.
deprecated The behavior has been deprecated.
deprecated_delete The behavior has been removed.
deprecated_readonly The behavior has been deprecated.
duplicate_feature Two behaviors of the same type are inappropriately placed within the same rule.
feature_no_prompt_upgrade A new version of the behavior is available, requiring an upgrade.
feature_upgrade_required The property needs to be upgraded to replace a deprecated behavior.
feature_upgrade_required_readonly The property needs to be upgraded to replace a deprecated behavior, but this version can’t be edited. Create a new version if necessary.
feature_upgrade_required_viewonly A new version of the behavior is available, requiring an upgrade.
generic_behavior_issue.kss_not_object A new version of the behavior is available that may require a different set of options.
generic_behavior_issue.netstorage_group_not_available A specified NetStorage account is not associated with this property’s group.
generic_behavior_issue.origin_missing_auxlist_subtitle Your auxiliary certificate list specifies trusted items not reflected in what your origin behavior specifies. Confirm they are accurate, and contact your account team if there is a problem.
generic_behavior_issue.origin_missing_trust_ca_certs_from_underride Your auxiliary certificate list specifies trusted items not reflected in what your origin behavior specifies. Confirm they are accurate, and contact your account team if there is a problem.
generic_behavior_issue.origin_missing_trust_certs_from_underride Your auxiliary certificate list specifies trusted items not reflected in what your origin behavior specifies. Confirm they are accurate, and contact your account team if there is a problem.
generic_behavior_issue.origin_valid_cn_missing_values_from_underride_error The origin behavior’s customValidCnValues option is missing CN/SAN match values from the auxiliary certificates list, so an ordinarily trusted certificate may not be trusted, and may result in a service outage.
generic_behavior_issue.origin_valid_cn_missing_values_from_underride_warning Confirm the origin behavior’s customValidCnValues option includes all CN/SAN values from the auxiliary certificates list.
generic_behavior_issue.origin_valid_cn_wildcard Values in the origin behavior’s customValidCnValues option may contain a star (*) character, but it is interpreted literally.
incompatible_condition There is an incompatibility with a specific criteria within the same rule.
incompatible_features There is an incompatibility with a specific behavior within the same rule.
incompatible_stages.multiple There is an incompatibility with a set of match criteria.
incompatible_stages.none There is an incompatibility with a criteria in a parent rule.
incompatible_stages.one There is an incompatibility with a criteria that appears in the same rule.
required_feature The default rule requires a behavior for the property to work.
too_many_instances There are more instances of the specified behavior than allowed within a property.
unknown_condition The criteria is not supported, and you need to remove it before activating your property.
unknown_feature The behavior is not supported, and you need to remove it before activating your property.
unknown_feature_attribute The behavior or criteria specifies an unknown option.

Option Value Errors

These errors may be listed within Rule objects, and may prevent you from activating the property version:

Type Description
generic_behavior_issue.table_option_dup_row The option specifies duplicated items.
illegal_option_value_format.features A behavior option’s data type is invalid.
illegal_option_value_format.matches A criteria option’s data type is invalid.
insecure_string_value Option values may not specify %( text.
non_ascii The option specifies non-ASCII characters.
option_empty The option may not specify an empty value.
option_required.features The behavior is missing a required option.
option_required.matches The criteria is missing a required option.
option_required_when.features The behavior is missing an option that’s required when another of its options is set to a specific value.
option_required_when.matches The criteria is missing an option that’s required when another of its options is set to a specific value.

Variable-Related Errors

These errors may be listed within Rule objects, and may prevent you from activating the property version:

Type Description
cannot_validate The option can’t be validated because the value of its embedded variable can only be known at runtime.
duplicate_variable There is more than one declared variable with the same name.
empty_variable_name The name of the variable can’t be empty.
internal_variable_in_xml An advanced behavior specifies a variable that uses a reserved prefix.
no_variable_support Your contract does not support use of variables.
syntax_error_in_variable_expression.illegal_expression There is a format error in a variable expression.
syntax_error_in_variable_expression.illegal_prefix There is an illegal prefix in a variable expression.
syntax_error_in_variable_expression.missing_end_token There is a missing end token in a variable expression.
unknown_variable_name An undeclared variable name was invoked.

Metadata Errors

These errors may be listed within Rule objects, and may prevent you from activating the property version:

Type Description
advanced_override_metadata_enabled A rule specifies advanced metadata that potentially overrides other configurations specified in previous rules.
badly_formatted_xml The behavior specifies invalid XML metadata.
conflicting_xml A behavior may not work as expected because advanced metadata may cause conflicts.

Contract, Account, and CP Code Errors

Code Type Problem
429 cpcode/rate-limit-reached You made too many CP code requests. Try again later.
403 cpcode/invalid-services The current product does not allow you to create CP codes.

These errors may be listed within Rule or Hostname objects, and may prevent you from activating the property version:

Type Description
advanced_cpcodes_outside_account_cp_validated_false The property invokes a CP code not provisioned under this account, and Origin Domains will be enforced. Contact your account representative for more information.
advanced_cpcodes_outside_account_cp_validated_true The property invokes a CP code not provisioned under this account, and Origin Domain enforcement is disabled. Choose different CP codes, or move them into the current account.
advanced_cpcodes_outside_group_or_contract The property invokes a CP code that doesn’t belong to its group or contract.
fixed_limit_exceeded A limit has been exceeded for the property.
generic_behavior_issue.cpcode_created_recently The property invokes a recently created CP code that may not have fully propagated across the network. Activating the property version may disrupt your service.
generic_behavior_issue.cpcode_not_available The specified CP code can’t be used with this property. If you just created the CP code, try again later.
limit_key.elements_per_property The property exceeds the number of allowed behaviors and criteria.
limit_key.max_nested_rules The property exceeds the number of nested rules allowed.
not_granted_by_modules_on_contract Your current contract does not include a necessary module.
not_granted_by_modules_on_contract_readonly Your current contract does not include a necessary module.
product_behavior_issue.cpcode_incorrect_product The CP code is not configured for use with this property’s product, which may affect how traffic is reported.
product_not_on_contract The product is not available on your contract. Add the product to the contract, or switch the property to a different product or contract.

Criteria-specific Errors

These errors relate to how specific match criteria execute. They may be listed within Rule objects, and may prevent you from activating the property version.

Type Description
cloudlets_origin_group For cloudletsOrigin criteria to work, there must be an allowCloudletsOrigins placed within a parent rule.
incompatible_origin_type The cloudletsOrigin criteria only works when the origin behavior’s originType is set to CUSTOMER, NET_STORAGE, or APPLICATION_LOAD_BALANCER.
incompatible_with_any_conditions Specifying cloudletsOrigin along with any other criteria may make the origin inaccessible during a client request.
need_allowpatch To use requestMethod to match PATCH requests, you need to enable the allowPatch behavior.
need_allowpost To use requestMethod to match POST requests, you need to enable the allowPost behavior.
need_token_verify_behavior The tokenAuthorization match requires a verifyTokenAuthorization behavior in a parent rule with its failureResponse option disabled.
need_webdav To use requestMethod to match the specified method, you need to enable the webdav behavior.
onlyonedge Criteria such as clientIp, clientIpVersion, userLocation, and userNetwork only match on edge servers, not when requests are forwarded to other Akamai servers. Contact your Akamai representative for guidance.
options_with_webdav Requests that specify the OPTIONS method are always passed to the origin, so you can’t use requestMethod to match them.
origin_is_required The cloudletsOrigin behavior must be paired with an origin behavior.
requires_spdy The bucket criteria can only be used along with the spdy behavior.
should_vary_by_user_agent When modifying content based on the deviceCharacteristic, you should use the modifyOutgoingResponseHeader behavior to specify a Vary: User-Agent header.
suggest_audiencesegmentation Rather than randomly segmenting your traffic, consider applying audienceSegmentation to divide users into different groups based on a persistent cookie.
upper_lower_warning The match specifies a lowerBound value that is greater than the upperBound.
warn_use_headers Requests that don’t include an X-Forwarded-For header do not match. Consider disabling the useOnlyFirstXForwardedForIp option.

Behavior-specific Errors

These errors relate to how specific behaviors execute. They may be listed within Rule objects, and may prevent you from activating the property version.

Type Description
206override The responseCode behavior’s 206override option allows the 206 response to be overwritten, not recommended because it applies to byte-range responses. Please confirm you want to do this, and contact your Akamai representative for guidance.
advanced_on_image_management_off The imageManager behavior is configured to use a custom policy, but the behavior is disabled, so it has no effect.
advanced_on_warning When overriding the default policy, if the specified policyToken is not found, imageManager applies the default and does not save the one you specified.
applicationloadbalancer_needed For an APPLICATION_LOAD_BALANCER origin to work, an applicationLoadBalancer behavior must also be enabled.
aws_verificationmode_validation To set a third-party origin hostname, set the verificationMode to THIRD_PARTY or CUSTOM.
basic_redirect_conflict You can’t specify both the redirect and redirectplus behaviors.
beware_of_conditions A behavior that implements a persistent connection may mean that a specified condition no longer works.
cache_key_case_off_ext_case_on With cacheKeyIgnoreCase enabled, you should not specify a case-sensitive match, otherwise two different requests that vary only by case may get different results, even though they refer to the same cached object.
cache_key_case_off_filename_case_on With cacheKeyIgnoreCase enabled, you should not specify a case-sensitive match, otherwise two different requests that vary only by case may get different results, even though they refer to the same cached object.
cache_key_case_off_path_case_on With cacheKeyIgnoreCase enabled, you should not specify a case-sensitive match, otherwise two different requests that vary only by case may get different results, even though they refer to the same cached object.
cachekeyqueryparams Since NET_STORAGE origin servers do not honor query strings, set cacheKeyQueryParams to IGNORE_ALL to avoid more than cache key for the same object.
caching You are potentially caching content identified as personallyIdentifiableInformation, so you should set the caching behavior to NO_STORE or BYPASS_CACHE.
caching_bypass The specified behavior only applies to cachable content, not when caching is set to NO_STORE or BYPASS_CACHE.
caching_enabled The sureRoute behavior only applies when caching is set to NO_STORE.
caching_maxage For best performance when using a NET_STORAGE origin, set the caching ttl to over 10 minutes.
can_not_mix_delegate_and_custom You can’t specify more than one origin behavior with a verificationMode of both PLATFORM_SETTINGS and CUSTOM.
centralauth A NET_STORAGE origin can’t be used along with centralAuthorization.
changing_cpcode_warning CP codes specified by imageManager affect cached images. If you change the CP codes after deploying the images in a production environment, image caches get refreshed, which may overload your origin.
conflict_dscaching Applying a behavior that modifies Cache-Control or Expires headers may interfere with caching when both are applied to the same request.
cookie_value_empty_need_to_disable_session_persistence The edgeLoadBalancingOrigin behavior’s enableSessionPersistence is on, but edgeLoadBalancingDataCenter is missing a cookieName.
cookie_value_set_need_to_enable_session_persistence The edgeLoadBalancingOrigin behavior’s enableSessionPersistence is off, but edgeLoadBalancingDataCenter specifies a cookieName that does not work.
cpcode_behavior_not_allowed The cpCode behavior can’t appear within the same rule as imageManager, which specifies its own CP code settings.
customer_origin If the origin server does not support etags, the largeFileOptimization behavior may not work correctly, and data may be corrupted.
disable_gzip When enabling edgeSideIncludes, do not set gzipResponse to ALWAYS work, otherwise content goes through compression and decompression unnecesarily.
dontallow_caching The downgradeProtocol behavior is not allowed when caching is set to NO_STORE or BYPASS_CACHE.
dontallow_delete The downgradeProtocol behavior is not allowed along with allowDelete.
dontallow_modoutgoingreqheader The downgradeProtocol behavior is not allowed along with modifyOutgoingRequestHeader.
dontallow_pii The downgradeProtocol behavior is not allowed for content marked as personallyIdentifiableInformation.
dontallow_post The downgradeProtocol behavior is not allowed along with allowPost.
dontallow_put The downgradeProtocol behavior is not allowed along with allowPut.
downstream_bust The shutr behavior busts downstream caches to prevent non-Akamai proxies from tampering with content. If downstreamCache is set to values other than BUST, shutr overrides it.
downstream_caching_indeterminate A specified behavior may expose content identified as personallyIdentifiableInformation. You should set a downstreamCache to BUST the cache, or ALLOW it but with sendPrivate enabled.
downstream_caching_without_private A specified behavior may expose content identified as personallyIdentifiableInformation. You should set a downstreamCache to BUST the cache, or ALLOW it but with sendPrivate enabled.
elb_must_use_other_cn When using an EDGE_LOAD_BALANCING_ORIGIN_GROUP origin, you can’t specify {{Origin Hostname}} in the customValidCnValues.
elb_origin_definition_needed To specify an origin of EDGE_LOAD_BALANCING_ORIGIN_GROUP, you must also enable an edgeLoadBalancingOrigin behavior that defines the origin.
elb_origin_missing An edgeLoadBalancingAdvanced behavior requires an accompanying edgeLoadBalancingOrigin.
empty_cookie_value_and_failover_rules The edgeLoadBalancingDataCenter is invalid because its cookie value is empty and enableFailover is turned off.
extension_match_advised To apply this behavior to large files, you should match the fileExtension or otherwise avoid applying the behavior to small files, for which it may cause a delay.
filename_match_advised You should enable limitBitRate with a filename, fileExtension, or path match.
g2o_modoutgoing_warning You can’t use modifyOutgoingResponseHeader to modify the X-Akamai-G2O-Auth-Data and X-Akamai-G2O-Auth-Sign headers specified by the g2oheader behavior.
http2_requires_secure The http2 behavior requires that the property is_secure.
includeallqs If one cacheId behavior is set to INCLUDE_ALL_QUERY_PARAMS, there can’t be another in the same rule that includes or excludes specific parameters.
includeqs If one cacheId behavior is set to include a specific set of query parameters, there can’t be another in the same rule that excludes others.
incompatible_opts The failAction behavior is not compatible when the origin is set to EDGE_LOAD_BALANCING_ORIGIN_GROUP.
incompatible_originbasepath You can’t apply the rewriteUrl and baseDirectory behaviors to the same request.
incompatible_ppf_siteshield The siteShield behavior is incompatible with predictivePrefetching.
incompatible_with_any_conditions You can’t specify allowCloudletsOrigins with any matching criteria.
incompatible_with_any_features You can’t specify allowCloudletsOrigins along with any other behaviors. It must be alone in its own rule.
incompatible_with_netstorage deliveryReceipt is not compatible when the origin is NET_STORAGE.
incompatibleesi You may only enable akamaizer with edgeSideIncludes.
incompatibleredirect The responseCode behavior may not work as expected along with redirect, because they use different status codes.
invalid_origincertstohonor_options The origin hostname is AWS and the verificationMode is CUSTOM, but the originCertsToHonor is not set to STANDARD_CERTIFICATE_AUTHORITIES or COMBO.
ip_address_origin You should specify your origin server as a hostname. IP addresses may be abruptly reassigned and negatively affect your service.
lfo_with_td_ch2 A tieredDistribution whose tieredDistributionMap doesn’t specify CH or CH2 can’t be applied within a secure property along with a largeFileOptimization whose useVersioning is enabled.
logging_cookies You are using report to log values for cookies in responses identified as personallyIdentifiableInformation. Make sure the cookies are not exposing sensitive information.
min_24hr_ttl_required Any rule that contains imageManager must also specify a caching behavior with a ttl of at least 1 day.
missing_edge_image_converter The watermarkUrl behavior requires a corresponding edgeImageConversion in the same rule or in a child rule.
missing_elb_origin An edgeLoadBalancingDataCenter requires an accompanying edgeLoadBalancingOrigin.
missing_origin To use simulateErrorCode for the ERR_NO_GOOD_FWD_IP error, healthDetection must be enabled.
mobile_302_conflict Mobile redirect only supports the 302 status code.
mobile_default_conflict A mobile redirect can’t be used in the same rule as a default redirect.
must_be_in_cloudlets_origin_group To enable an origin of EDGE_LOAD_BALANCING_ORIGIN_GROUP, you must also define a cloudletsOrigin rule.
need_additional_match The prefetchable behavior needs to be enabled by a filename or fileExtension match.
need_customer_origin The downgradeProtocol behavior is only allowed when the origin is set to CUSTOMER.
need_data_center_defined To enable the edgeLoadBalancingOrigin behavior’s enableSessionPersistence option, you need to configure an edgeLoadBalancingDataCenter.
needs_akamaizer The akamaizer behavior needs to be enabled for akamaizerTag to work.
needs_akamaizertag There must be at least one akamaizerTag for akamaizer to work.
needs_content_match The edgeSideIncludes behavior may only be used in rules with matching criteria such as path, contentType, or filename.
needs_contenttype You may only enable akamaizer within a contentType match.
netstorage_hostname_warning The origin needs to be set to NET_STORAGE if the hostname is a subdomain of download.akamai.com, upload.akamai.com, or postfile.akamai.com.
no_property_hostname_cachekey You may not use instantConfig when the cacheKeyHostname of the origin is set to REQUEST_HOST_HEADER.
nonce_secret_key_warning The g2oheader behavior’s nonce should be different than its secretKey.
not_compatible You can’t use verifyTokenAuthorization when segmentedContentProtection is enabled.
not_validation_html_warning The constructResponse response body should be valid XHTML.
notallow_ext The downgradeProtocol behavior can’t be enabled by a fileExtension match.
notallow_filename The downgradeProtocol behavior can’t be enabled by a filename match.
notallow_protocol The downgradeProtocol behavior can’t be enabled by a requestProtocol match.
objects_cant_exceed_1mb Objects served with edgeSideIncludes may not be larger than 1MB.
origin_acl_must_be_updated_manually An old origin version specifies a cachekeyhostname of requesthostheader.
origin_acl_must_be_updated_manually_elb An old origin version specifies an elb_origin_group of type.
origin_elb_definition_warning edgeLoadBalancingOrigin doesn’t work unless the origin is set to EDGE_LOAD_BALANCING_ORIGIN_GROUP.
origin_g2o_error You should not use the g2oheader behavior when the origin is set to NET_STORAGE.
origin_netstorage The origin can’t be set to NET_STORAGE if segmentedMediaOptimization is set to stream LIVE.
performance_warning The akamaizer behavior is not recommended for sites that routinely serve more than 100 hits per second.
prefetch The instant behavior is a superset of prefetch, and they are mutually exclusive. Remove either behavior.
prefetching_never_enabled The prefetchable behavior has no effect unless you apply prefetch to the page users access, and which contains links to the prefetchable objects.
prefetching_with_ss The siteShield behavior is incompatible with prefetching.
prune_query_whenns A NET_STORAGE origin server ignores query parameters, so it’s more efficient to disable the rewriteUrl behavior’s keepQueryString option.
receiptdelivery_requires_allow_post Applying deliveryReceipt requires that you enable allowPost.
receiptdelivery_requires_bypass_cache Applying deliveryReceipt requires that you set caching to BYPASS_CACHE.
receiptdelivery_requires_secure deliveryReceipt requires that the property is_secure.
regex_validation_notsecure When siteShield is used in a non-secure property, the domain name of the ssmap must end with .akamai.net.
regex_validation_secure When siteShield is used in a secure property, the domain name of the ssmap must end with .akamaiedge.net.
regex_validation_sureroute The sureRoute behavior’s customMap must be a subdomain of akasrg.akamai.com.
requireakamaizer The savePostDcaProcessing behavior doesn’t work properly unless akamaizer is enabled.
required_mdc_for_saas_cname For a behavior to specify a CNAME chain, the instantConfig behavior must also be enabled, or the property must be secure.
required_negative_caching When your origin is set to NET_STORAGE, set the cacheError with a ttl of at least 30 seconds.
required_third_party_set The origin hostname is AWS, the verificationMode is set to CUSTOM, and originCertsToHonor is set to STANDARD_CERTIFICATE_AUTHORITIES or COMBO, but standardCertificateAuthorities doesn’t include THIRD_PARTY_AMAZON.
requires_caching_enabled To set the cache’s ID, the caching behavior must be enabled.
requires_extension_match The imageManager behavior requires a fileExtension match. ???
requires_hoit_match The http2 and spdy behaviors can only be enabled within a hostname match.
requires_mfro The randomSeek behavior works best when mediaFileRetrievalOptimization is enabled.
requires_nonsecure To apply instantConfig requires a non-secure property.
requires_origin_cacheley_inc_hh You can’t use cacheKeyRewrite when the origin behavior’s cacheKeyHostname is set to REQUEST_HOST_HEADER.
requires_requestmethod_match You can only enable the webdav behavior when matching a requestMethod.
requirescaching When using cachePost, you should also use caching to define a caching strategy.
requirespost The savePostDcaProcessing behavior requires either allowPost or cachePost to be enabled.
requirespostcaching The savePostDcaProcessing behavior requires cachePost to be enabled.
responsecode_conflict The response code defined in constructResponse and responseCode do not match.
saas_origin_hostname_cn When using a SAAS_DYNAMIC_ORIGIN origin, you can’t specify {{Origin Hostname}} in the customValidCnValues.
salt_deprecated The verifyTokenAuthorization behavior’s salt option will be removed in a future release, so you should remove it from your code.
scheduledinvalidation When the origin is NET_STORAGE, the scheduleInvalidation behavior’s repeatInterval must be at least 5 minutes.
secret_key_warning The g2oheader behavior’s secretKey must be at least 10 alphanumeric characters long.
spdy_requires_secure The spdy behavior requires that the property is_secure.
sr_ss_map_mismatch A sureRoute behavior specifies a type of CUSTOM_MAP, and the customMap does not match what is specified by siteShield.
sr_with_ss With siteShield enabled, the optimiziation type for sureRoute should be CUSTOM_MAP.
ss_incompatible The instant behavior is incompatible with siteShield.
ssl_custom_warning_aux_list In an early version of the origin behavior, origin_cert_delete is set to custom.
ssl_custom_warning_expert Due to the security risk, Akamai strongly recommends you consult with your organization’s security expert before configuring the origin SSL certificate verification settings. If you are the security expert and have any questions, contact your account team.
ssl_custom_warning_test_staging If you are changing your origin SSL certificate verification settings, to avoid a service outage Akamai strongly recommends testing on the staging network before activating on production.
ssl_delegate_warning_intro The origin behavior has been enhanced to address the FOSSL exploit.
ssl_delegate_warning_rotate The origin behavior has been enhanced to address the FOSSL exploit.
ssl_warn_warning An older origin version specifies a verificationMode of INSECURE.
subrules_need_condition For allowCloudletsOrigins to work, you need to nest at least one rule with a single cloudletsOrigin criteria.
suggest_edgeredirector Instead of redirect, consider using the edgeRedirector Cloudlet, which allows non-IT staff to manage large numbers of redirects.
sureroute_required When applying instant to content whose caching is NO_STORE, the content must also have sureRoute enabled or it is not prefetched.
tcip_allow_clients_to_set_on The origin is configured to allow clients to set the True-Client-IP header, meaning the IP value sent to the origin may not be the one the client used to connect to the edge server. While this may be useful for testing, it may allow users to bypass IP-based restrictions on your origin server.
tcpoptisdeprecated The tcpOptimization behavior is deprecated, and you should remove it.
td_with_modify_inplace The tieredDistribution behavior can’t be enabled when the largeFileOptimization behavior’s useVersioning is disabled.
td_with_ss The siteShield behavior is incompatible with tieredDistribution because both determine which Akamai servers connect directly to the origin.
third_party_verificationmode Setting the origin’s verificationMode to THIRD_PARTY is incompatible with the specified originType.
tiereddistribution_required When applying instant to cacheable content, it must also have tieredDistribution enabled or it is not prefetched.
unpurgeable Enabling a behavior within a specified criteria prevents Content Control Utility from purging by URL. Contact your Akamai representative for guidance.
urlrewrite_incompatible When using removeQueryParameter, the rewriteUrl behavior’s keepQueryString must also be enabled.
usebody The cachePost behavior specifies a useBody of MD5 or QUERY, but there is no accompanying cacheId.
warn_not_connnectingip When setting denyAccess, disable the match’s useOnlyFirstXForwardedForIp to prevent malicious end users from using X-Forwarded-For headers to bypass the policy.
warn_regex Test any regular expressions you specify in rewriteUrl on the staging network and contact your Akamai representative if you are uncertain how to use this option.
wildcard_match_advised You should enable limitBitRate with a filename, fileExtension, or path match.
with_ignore_case To apply cacheKeyIgnoreCase, you need to lowercase the elements specified by an accompanying cacheId, otherwise they never match.
within_cloudlets_origins_group This Cloudlet behavior may not work as expected when added to the same rule that sets the cloudletsOrigin. Consider moving it to a different rule.

Other Errors

The following may appear as standalone 400 errors:

Code Type Problem
400 invalid-rule-format The specified rule format is not supported. Learn more.
400 toolkit/password-needs-rotation The password for the user attached to the given authorization token must be rotated.

The following fallback error may appear when modifying a rule tree:

Type Description
unknown_message Unknown rule tree validation error.

Last modified: 5/24/2017