Send Docs Feedback

Note: Most user interface tasks can be performed in Edge Classic or the New Edge experience. For an overview, getting started topics, and release notes specific to the New Edge experience, see the docs.

Policy error reference

Access Control policy

This section describes the error messages and flow variables that are set when this policy triggers an error. This information is important to know if you are developing fault rules to handle errors. To learn more, see What you need to know about policy errors and Handling faults.

Error code prefix

steps.accesscontrol (What's this?)

Runtime errors

These errors can occur when the policy executes.

Error name HTTP status Cause
ClientIpExtractionFailed   See fault string.
IPDeniedAccess 403 See fault string.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name Cause
InvalidIPAddress See fault string.
InvalidIPv4Address See fault string.
InvalidIPv6Address See fault string.
InvalidRulePattern See fault string.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables set (Learn more) Where Example
[prefix].[policy_name].failed The [prefix] is acl.
The [policy_name] is the name of the policy that threw the error.
acl.AC-AllowAccess.failed = true
fault.[error_name] [error_name] = The specific error name to check for as listed in the table above. fault.name = "IPDeniedAccess"

Example error response

For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

{  
   "fault":{  
      "detail":{  
         "errorcode":"steps.accesscontrol.IPDeniedAccess"
      },
      "faultstring":"Access Denied for client ip : 52.211.243.3"
   }
}

Example fault rule

<FaultRule name="IPDeniedAccess">
    <Step>
        <Name>AM-IPDeniedAccess</Name>
        <Condition>(fault.name Matches "IPDeniedAccess") </Condition>
    </Step>
    <Condition>(acl.failed = true) </Condition>
</FaultRule>

Access Entity policy

For related information, see What you need to know about policy errors and Handling faults.

Runtime errors

None.

Deployment errors

Error name Fault string HTTP status Occurs when
InvalidEntityType Invalid type [entity_type] in ACCESSENTITYStepDefinition [policy_name] N/A The entity type used must be one of the supported types.

Assign Message policy

This section describes the error messages and flow variables that are set when this policy triggers an error. This information is important to know if you are developing fault rules for a proxy. To learn more, see What you need to know about policy errors and Handling faults.

Error code prefix

steps.assignmessage (What's this?)

Runtime errors

These errors can occur when the policy executes.

Error name HTTP status Cause
UnresolvedVariable 500 A flow variable referenced in the policy does not exist. Be sure that the variable is in scope - some of the built-in Edge variables are only available in certain flow contexts.
VariableOfNonMsgType 500 The policy tried to assign a value to a non-message type variable. Message type variables include request and response. They also can be custom variables that are of type message. You might see this in the <Copy> element if you set the source attribute to a variable that is not of type Message.
SetVariableFailed 500 The policy was not able to set a variable. See the fault string for the name of the unresolved variable.
InvalidIndex 500 The index must be geater than zero when specified in the Copy and Remove operations. For example, a query parameter can have multiple values. This error occurs if you specify an invalid index, such as 0 or a negative number.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name Cause
InvalidVariableName The policy schema validation failed because a variable name is invalid.
InvalidPayload A payload specified in the policy is invalid.

Fault variables

These variables are set when this policy triggers an error at runtime. For more information, see What you need to know about policy errors.

Variables set (Learn more) Where Example
[prefix].[policy_name].failed The [prefix] is assignmessage.
The [policy_name] is the name of the policy that threw the error.
assignmessage.AM-SetResponse.failed = true
fault.name = [error_name] [error_name] is the specific error name to check for as listed in the table above. fault.name = "UnresolvedVariable"

Example error response

For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

{  
   "fault":{  
      "detail":{  
         "errorcode":"steps.assignmessage.VariableOfNonMsgType"
      },
      "faultstring":"AssignMessage[AM-SetResponse]: value of variable is not of type Message"
   }
}

Example fault rule

<FaultRule name="Assign Message Faults">
    <Step>
        <Name>AM-CustomNonMessageTypeErrorResponse</Name>
        <Condition>(fault.name Matches "VariableOfNonMsgType") </Condition>
    </Step>
    <Step>
        <Name>AM-CustomSetVariableErrorResponse</Name>
        <Condition>(fault.name = "SetVariableFailed")</Condition>
    </Step>
    <Condition>(assignmessage.failed = true) </Condition>
</FaultRule>

Basic Authentication policy

This section describes the error messages and flow variables that are set when this policy triggers an error. This information is important to know if you are developing fault rules to handle errors. To learn more, see What you need to know about policy errors and Handling faults.

Error code prefix

steps.basicauthentication (What's this?)

Runtime errors

These errors can occur when the policy executes.

Error name HTTP status Cause
UnresolvedVariable 500 The required source variables for the decode or encode are not present. This error can only occur if IgnoreUnresolvedVariables is false.
InvalidBasicAuthenticationSource 500 On a decode when the incoming Base64 encoded string does not contain a valid value or the header is malformed (e.g., does not start with "Basic").

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name Occurs when
UserNameRequired The <User> element must be present for the named operation. See the fault string.
PasswordRequired The <Password> element must be present for the named operation. See the fault string.
AssignToRequired The <AssignTo> element must be present for the named operation. See the fault string.
SourceRequired The <Source> element must be present for the named operation. See the fault string.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables set (Learn more) Where Example
[prefix].[policy_name].failed The [prefix] is BasicAuthentication.
The [policy_name] is the name of the policy that threw the error.
BasicAuthentication.BA-Authenticate.failed = true
fault.[error_name] [error_name] = The specific error name to check for as listed in the table above. fault.name = "UnresolvedVariable"

Example error response

For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

{  
   "fault":{  
      "detail":{  
         "errorcode":"steps.basicauthentication.UnresolvedVariable"
      },
      "faultstring":"Unresolved variable : request.queryparam.password"
   }
}

Example fault rule

<FaultRule name="Basic Authentication Faults">
    <Step>
        <Name>AM-UnresolvedVariable</Name>
        <Condition>(fault.name Matches "UnresolvedVariable") </Condition>
    </Step>
    <Step>
        <Name>AM-AuthFailedResponse</Name>
        <Condition>(fault.name = "InvalidBasicAuthenticationSource")</Condition>
    </Step>
    <Condition>(BasicAuthentication.BA-Authentication.failed = true) </Condition>
</FaultRule>

Concurrent Rate Limit policy

This section describes the error messages and flow variables that are set when this policy triggers an error. This information is important to know if you are developing fault rules for a proxy. To learn more, see What you need to know about policy errors and Handling faults.

Error code prefix

policies.concurrentratelimit (What's this?)

Runtime errors

These errors can occur when the policy executes.

Error name HTTP status Occurs when
ConcurrentRatelimtViolation 503

ConcurrentRatelimit connection exceeded. Connection limit : {0}

Note: The Error code shown on the right is correct, although it contains a misspelling ("limt"). Please be sure to use the code exactly as shown here when creating fault rules to trap this error. 

Deployment errors

Error name Occurs when
InvalidCountValue ConcurrentRatelimit invalid count value specified.
ConcurrentRatelimitStepAttachment\
NotAllowedAtProxyEndpoint
Concurrent Ratelimit policy {0} attachment is not allowed at proxy request/response/fault paths. This policy must be placed on the Target Endpoint.
ConcurrentRatelimitStepAttachment\
MissingAtTargetEndpoint
Concurrent Ratelimit policy {0} attachment is missing at target request/response/fault paths. This policy must be placed in the Target Request Preflow, Target Response Postflow, and DefaultFaultRule.
InvalidTTLForMessageTimeOut ConcurrentRatelimit invalid ttl value specified for message timeout. It must be a positive integer. 

 

Fault variables

These variables are set when this policy triggers an error. For more information, see What you need to know about policy errors.

Variables set (Learn more) Where Example
[prefix].[policy_name].failed The fault variable [prefix] is concurrentratelimit.
The [policy_name] is the name of the policy that threw the error.
concurrentratelimit.CRL-RateLimitPolicy.failed = true
fault.[error_name] [error_name] = The specific error name to check for as listed in the table above.

fault.name Matches "ConcurrentRatelimtViolation"

Note: The Error code shown in the example is correct, although it contains a misspelling ("limt"). Please be sure to use the code exactly as shown here when creating fault rules to trap this error. 

Example error response

If the rate limit is exceeded, the policy returns only an HTTP status 503 to the client.

Example fault rule

<FaultRules>
    <FaultRule name="Quota Errors">
        <Step>
            <Name>JavaScript-1</Name>
            <Condition>(fault.name Matches "ConcurrentRatelimtViolation") </Condition>
        </Step>
        <Condition>concurrentratelimit.CRL-RateLimitPolicy.failed=true</Condition>
    </FaultRule>
</FaultRules>

Extract Variables policy

This section describes the error messages and flow variables that are set when this policy triggers an error. This information is important to know if you are developing fault rules for a proxy. To learn more, see What you need to know about policy errors and Handling faults.

Error code prefix

steps.extractvariables (What's this?)

Runtime errors

These errors can occur when the policy executes.

Error name HTTP status Cause
ExecutionFailed 500

The policy tried to parse input that is malformed or otherwise invalid.

The policy tried to parse XML with a namespace that is not declared in the <Namespace> element.

SourceMessageNotAvailable 500 A variable specified in <Source> is out of scope or can't be resolved. For example, if the policy executes in the request flow, the <Source> variable cannot be set to response or error.
SetVariableFailed 500 The policy was not able to set a variable value.
ImmutableVariable 500 A variable used in the policy is immutable. The policy was unable to set this variable.
VariableResolutionFailed 500 The policy could not resolve a variable. Be sure the variable you are trying to set exists in the runtime flow.
UnsupportedOperation 500 The policy tried to perform an unsupported operation on named flow variables.
InvalidJSONPath 500 A JSON path used in the policy is invalid.
UnableToCast 500 The policy was unable to cast a variable.
JSONPathCompilationFailed 500 The policy was unable to compile a JSON path expression.
JsonPathParsingFailure 500 The policy was unable to parse a JSON path to extract data into flow variables.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name Cause
NothingToExtract A required element is missing from the policy. At least one of these elements is required: URIPath, QueryParam, Header, FormParam, XMLPayload, JSONPayload.
NONEmptyPrefixMappedToEmptyURI The <XMLPayload> element is not configured properly. A non-empty prefix cannot be mapped to an empty URI.
DuplicatePrefix The <XMLPayload> element is not configured properly. There is a duplicate prefix.
NoXPathsToEvaluate There are no XPaths to evaluate. An <XPath> child element must be specified.
EmptyXPathExpression The policy has invalid configuration of the <Variable> child element of an <XMLPayload> element.
NoJSONPathsToEvaluate You do not specify a <JSONPath> child element where it is required.
EmptyJSONPathExpression The policy has an empty child element <JSONPath> in a element <JSONPayload>.
MissingName The name attribute is missing from a policy element that requires it.
PatternWithoutVariable <Pattern> element that does not have a variable specified. The element requires the name of the variable in which extracted data will be stored.
CannotBeConvertedToNodeset The result of an XPath expression cannot be converted to type nodeset.
JSONPathCompilationFailed The policy could not compile a specified JSON Path.
InstantiationFailed The policy could not be instantiated.
XPathCompilationFailed The policy could not compile a specified XPath. Be sure to declare any namespaces that are used in the XPath.
InvalidPattern A <Pattern> element is invalid in one of these elements: URIPath, QueryParam, Header, FormParam, XMLPayload, JSONPayload.

Fault variables

These variables are set when this policy triggers an error at runtime. For more information, see What you need to know about policy errors.

Variables set (Learn more) Where Example
[prefix].[policy_name].failed The [prefix] is extractvariables.
The [policy_name] is the name of the policy to check.
extractvariables.EV-ParseJsonResponse.failed = true
fault.[error_name] [error_name] = The specific error name to check for as listed in the table above. fault.name = "SourceMessageNotAvailable"

Example error response

For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

{  
   "fault":{  
      "detail":{  
         "errorcode":"steps.extractvariables.SourceMessageNotAvailable"
      },
      "faultstring":"request message is not available for ExtractVariable: EV-ParseJsonResponse"
   }
}

Example fault rule

<FaultRule name="Extract Variable Faults">
    <Step>
        <Name>AM-CustomErrorMessage</Name>
        <Condition>(fault.name = "SourceMessageNotAvailable") </Condition>
    </Step>
    <Condition>(extractvariables.EM-ParseJsonResponse.failed = true) </Condition>
</FaultRule>

Java Callout policy

This section describes the error messages and flow variables that are set when this policy triggers an error. This information is important to know if you are developing fault rules for a proxy. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Error name Fault string HTTP status Occurs when
ExecutionError Failed to execute JavaCallout. [policy_name] 500 See fault string.

 

Deployment errors

These errors can occur when the proxy containing the policy is deployed.

Error name Fault string HTTP status Occurs when
ResourceDoesNotExist Resource with name [name] and type [type] does not exist N/A The file specified in the <ResourceURL> element does not exist.
JavaCalloutInstantiationFailed Failed to instantiate the JavaCallout Class [classname] N/A The class file specified in the <ClassName> element is not in the jar.
IncompatibleJavaVersion Failed to load java class [classname] definition due to - [reason] N/A See fault string. See also Supported software and supported versions.
JavaClassNotFoundInJavaResource Failed to find the ClassName in java resource [jar_name] - [class_name] N/A See fault string.
JavaClassDefinitionNotFound Failed to load java class [class_name] definition due to - [reason] N/A See fault string.
NoAppropriateConstructor No appropriate constructor found in JavaCallout class [class_name] N/A See fault string.
NoResourceForURL Could not locate a resource with URL [string] N/A See fault string.

Fault variables

These variables are set when this policy triggers an error. For more information, see What you need to know about policy errors.

Variables set (Learn more) Where Example
[prefix].[policy_name].failed [prefix]: javacallout
[policy_name]: The name of the policy to check.
javacallout.JC-GetUserData.failed = true
fault.[error_name] [error_name] = The specific error name to check for as listed in the table above. fault.name Matches "ExecutionError"

Example error response

{  
   "fault":{  
      "faultstring":"Failed to execute JavaCallout. [policy_name]",
      "detail":{  
         "errorcode":"javacallout.ExecutionError"
      }
   }
}

Example fault rule

<FaultRule name="JavaCalloutFailed">
    <Step>
        <Name>AM-JavaCalloutError</Name>
    </Step>
    <Condition>(fault.name Matches "ExecutionError") </Condition>
</FaultRule>

JavaScript policy

This section describes the error messages and flow variables that are set when this policy triggers an error. This information is important to know if you are developing fault rules for a proxy. To learn more, see What you need to know about policy errors and Handling faults.

Error code prefix

steps.javascript (What's this?)

Runtime errors

These errors can occur when the policy executes.

Error name HTTP
Status
Occurs when
ScriptExecutionFailed 500 A runtime error occurred in the JavaScript code. See the fault string for details.
ScriptExecutionFailedLineNumber 500 An error occurred in the JavaScript code. See the fault string for details.
ScriptSecurityError 500 A security error occurred when the JavaScript executed. See the fault string for details.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name Occurs when
WrongResourceType In the <ResourceURL> and <IncludeURL> elements, you must refer to a JavaScript file correctly using the jsc resource type. For example, here is the correct way to refer to the JavaScript file in the policy:
<ResourceURL>jsc://JavaScript-1.js</ResourceURL>
NoResourceForURL The <ResourceURL> and <IncludeURL> elements refer to a JavaScript file that does not exist.
ScriptCompilationFailed An error occured when Edge tried to compile the JavaScript code. Refer to the error message for details.

Fault variables

These variables are set when this policy triggers an error at runtime. For more information, see What you need to know about policy errors.

Variables set (Learn more) Where Example
[prefix].[policy_name].failed The [prefix] is javascript.
The [policy_name] is the name of the policy that threw the error.
javascript.JavaScript-1.failed = true
fault.[error_name] [error_name] is the specific error name to check for as listed in the table above. fault.name Matches "ScriptExecutionFailed"

Example error response

For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

{
  "fault": {
    "faultstring": "Execution of SetResponse failed with error: Javascript runtime error: "ReferenceError: "status" is not defined. (setresponse.js:6)\"",
    "detail": {
      "errorcode": "steps.javascript.ScriptExecutionFailed"
    }
  }
}

Example fault rule

<FaultRule name="JavaScript Policy Faults">
    <Step>
        <Name>AM-CustomErrorResponse</Name>
        <Condition>(fault.name Matches "ScriptExecutionFailed") </Condition>
    </Step>
    <Condition>(javascript.JavaScript-1.failed = true) </Condition>
</FaultRule>

JSON Threat Protection policy

This section describes the error messages and flow variables that are set when this policy triggers an error. This information is important to know if you are developing fault rules for a proxy. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Error name Fault string HTTP status Occurs when
ExceededContainerDepth JSONThreatProtection[policy_name]: Exceeded container depth at line [line_num] 500 See fault string.
ExceededObjectEntryCount JSONThreatProtection[policy_name]: Exceeded object entry count at line [line_num] 500 See fault string.
ExceededArrayElementCount JSONThreatProtection[policy_name]: Exceeded array element count at line [line_num] 500 See fault string.
ExceededObjectEntryNameLength JSONThreatProtection[policy_name]: Exceeded object entry name length at line [line_num] 500 See fault string.
ExceededStringValueLength JSONThreatProtection[policy_name]: Exceeded string value length at line [line_num] 500 See fault string.
SourceUnavailable JSONThreatProtection[policy_name]: Source [var_name] is not available 500 See fault string.
NonMessageVariable JSONThreatProtection[policy_name]: Variable [var_name] does not resolve to a Message 500 See fault string.
ExecutionFailed JSONThreatProtection[policy_name]: Execution failed. reason: [string] 500 See fault string.

Deployment errors

None.

Fault variables

These variables are set when this policy triggers an error. For more information, see What you need to know about policy errors.

Variables set (Learn more) Where Example
[prefix].[policy_name].failed [prefix]: jsonattack
[policy_name]: The name of the policy to check.
jsonthreatprotection.JTP-SecureRequest.failed = true
fault.[error_name] [error_name] = The specific error name to check for as listed in the table above. fault.name Matches "SourceUnavailable"

Example error response

{
  "fault": {
    "faultstring": "JSONThreatProtection[JPT-SecureRequest]: Execution failed. reason: JSONThreatProtection[JTP-SecureRequest]: Exceeded object entry name length at line 2",
    "detail": {
      "errorcode": "steps.jsonthreatprotection.ExecutionFailed"
    }
  }
}

Example fault rule

<FaultRule name="JSON Threat Protection Policy Faults">
    <Step>
        <Name>AM-CustomErrorResponse</Name>
        <Condition>(fault.name Matches "ExecutionFailed") </Condition>
    </Step>
    <Condition>(jsonattack.JPT-SecureRequest.failed = true) </Condition>
</FaultRule>

The JSONThreatProtection Policy types defines the following error codes:

JSON to XML policy

This section describes errors that this policy can return and flow variables that are set when the policy triggers an error. This information is important to know if you are developing fault rules for a proxy. To learn more, see What you need to know about policy errors and Handling faults.

Error code prefix

steps.jsontoxml (What's this?)

Runtime errors

These errors can occur when the policy executes.

Error name HTTP status Cause
SourceUnavailable 500 The variable specified in the <Source> element has to exist.
ExecutionFailed 500 See the fault string. Be sure the incoming message contains valid JSON.
OutputVariableIsNotAvailable 500 See the fault string.
InCompatibleTypes 500 See the fault string.
InvalidSourceType 500 See the fault string.

Deployment errors

None.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables set (Learn more) Where Example
[prefix].[policy_name].failed The variable [prefix] is jsontoxml.
The [policy_name] is the name of the policy that threw the error.
jsontoxml.JSON-to-XML-1.failed = true
fault.[error_name] [error_name] = The specific error name to check for as listed in the table above. fault.name Matches "SourceUnavailable"

Example error response

For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

{
  "fault": {
    "faultstring": "JSONToXML[JSON-to-XML-1]: Source xyz is not available",
    "detail": {
      "errorcode": "steps.json2xml.SourceUnavailable"
    }
  }
}

Example fault rule

<FaultRule name="JSON To XML Faults">
    <Step>
        <Name>AM-SourceUnavailableMessage</Name>
        <Condition>(fault.name Matches "SourceUnavailable") </Condition>
    </Step>
    <Step>
        <Name>AM-BadJSON</Name>
        <Condition>(fault.name = "ExecutionFailed")</Condition>
    </Step>
    <Condition>(jsontoxml.JSON-to-XML-1.failed = true) </Condition>
</FaultRule>

Key Value Map Operations policy

This policy uses the following error codes:

Error Code Message
SetVariableFailed

Failed to set variable {0} in KeyValueMapStepDefinition {1}

When getting values in encrypted key value maps, this error occurs if you fail to prefix the assignTo variable with "private." For example:

<Get assignTo="private.encryptedVar" index="1">
    <Key>
      <Parameter>foo</Parameter>
    </Key>
</Get>
RemoveVariableFailed Failed to remove variable {0} in KeyValueMapStepDefinition {1}
InvalidIndex Invalid index {0} in KeyValueMapStepDefinition {1}
KeyIsMissing Key element is missing in KeyValueMapStepDefinition {0}
ValueIsMissing Value element is missing in KeyValueMapStepDefinition {0}

 

LDAP policy

This policy uses the following error codes:

Error Code Message
InvalidAttributeName Invalid attribute name {0}.
InvalidSearchBase Search base can not be empty.
InvalidValueForPassword Invalid value for password field. It can not be empty.
InvalidSearchScope Invalid scope {0}. Allowed scopes are {1}.
InvalidUserCredentials Invalid user credentials.
InvalidExternalLdapReference Invalid external ldap reference {0}.
LdapResourceNotFound Ldap resource {0} not found.
BaseDNRequired Base DN required.
OnlyReferenceOrValueIsAllowed Only value or reference is allowed for {0}.
AttributesRequired At least one attribute required for search action.
UserNameIsNull User name is null.
SearchQueryAndUserNameCannotBePresent Both search query and username can not be present in the authentication action. Please specify either one of them.

 

Message Logging policy

This section describes the error messages and flow variables that are set when this policy triggers an error. This information is important to know if you are developing fault rules to handle errors. To learn more, see What you need to know about policy errors and Handling faults.

Error code prefix

steps.messagelogging (What's this?)

Runtime errors

These errors can occur when the policy executes.

Error name HTTP status Cause
StepDefinitionExecutionFailed 500 See fault string.

Deployment errors

None.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Proxy calls succeed when logging fails

There's a difference between policy errors and message logging errors. The flow variables here are populated only when the policy itself fails, not when message logging fails. Because message logging is first written to buffer, the API proxy will continue successful execution even if message logging ultimately fails (for example, if there's a connection failure to the external syslog provider). Be sure to check your logs on a regular basis to make sure logging is happening as expected.

Variables set (Learn more) Where Example
[prefix].[policy_name].failed The [prefix] is messagelogging.
The [policy_name] is the name of the policy that threw the error.
messagelogging.ML-LogMessages.failed = true
fault.[error_name] [error_name] = The specific error name to check for as listed in the table above. fault.name = "StepDefinitionExecutionFailed"

Example error response

For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

{  
   "fault":{  
      "detail":{  
         "errorcode":"steps.messagelogging.StepDefinitionExecutionFailed"
      },
      "faultstring":"Execution failed"
   }
}

Example fault rule

<FaultRule name="MessageLogging">
    <Step>
        <Name>ML-LogMessages</Name>
        <Condition>(fault.name Matches "StepDefinitionExecutionFailed") </Condition>
    </Step>
    <Condition>(messagelogging.ML-LogMessages.failed = true) </Condition>
</FaultRule>

Populate Cache policy

This section describes the error messages and flow variables that are set when this policy triggers an error. This information is important to know if you are developing fault rules for a proxy. To learn more, see What you need to know about policy errors and Handling faults.

Error code prefix

policies.populatecache (What's this?)

Runtime errors

Error name HTTP Status Occurs when
EntryCannotBeCached 500 An entry cannot be cached. The message object being cached is not an instance of a class that is Serializable.

Deployment errors

Error name Occurs when
InvalidCacheResourceReference The cache specified in the <CacheResource> element does not exist.
CacheNotFound The cache specified in the <CacheResource> element does not exist.

Fault variables

These variables are set when this policy triggers an error. For more information, see What you need to know about policy errors.

Variables set (Learn more) Where Example
[prefix].[policy_name].failed [prefix]: populatecache
[policy_name]: The name of the policy to check.
populatecache.POP-CACHE-1.failed = true
fault.[error_name] [error_name] = The specific error name to check for as listed in the table above. fault.name Matches "EntryCannotBeCached"

Example error response

{
  "fault": {
    "faultstring": "[entry] can not be cached. Only serializable entries are cached.",
    "detail": {
      "errorcode": "steps.populatecache.EntryCannotBeCached"
    }
  }
}

Example fault rule

<FaultRule name="Populate Cache Fault">
    <Step>
        <Name>AM-EntryCannotBeCached</Name>
        <Condition>(fault.name Matches "EntryCannotBeCached") </Condition>
    </Step>
    <Condition>(populatecache.POP-CACHE-1.failed = true) </Condition>
</FaultRule>

Lookup Cache policy

This section describes the error messages and flow variables that are set when this policy triggers an error. This information is important to know if you are developing fault rules for a proxy. To learn more, see What you need to know about policy errors and Handling faults.

Error code prefix

N/A

Runtime errors

This policy does not throw any runtime errors.

Deployment errors

Error name Occurs when
InvalidCacheResourceReference The cache specified in the <CacheResource> element does not exist.
InvalidTimeout The CacheLookupTimeoutInSeconds value must be greater than zero.
CacheNotFound The cache specified in the <CacheResource> element does not exist.

Fault variables

N/A

Example error response

N/A

Invalidate Cache policy

This section describes the error messages and flow variables that are set when this policy triggers an error. This information is important to know if you are developing fault rules for a proxy. To learn more, see What you need to know about policy errors and Handling faults.

Error code prefix

N/A

Runtime errors

This policy does not throw any runtime errors.

Deployment errors

Error name Occurs when
InvalidCacheResourceReference The cache specified in the <CacheResource> element does not exist.
CacheNotFound The cache specified in the <CacheResource> element does not exist.

Fault variables

N/A

Example error response

N/A

Response Cache policy

This section describes the error messages and flow variables that are set when this policy triggers an error. This information is important to know if you are developing fault rules for a proxy. To learn more, see What you need to know about policy errors and Handling faults.

Error code prefix

N/A

Runtime errors

This policy does not throw any runtime errors.

Deployment errors

Error name Occurs when
InvalidTimeout An invalid timeout value was specified in the <ExpirySettings> element.
InvalidCacheResourceReference The cache specified in the <CacheResource> element does not exist.
ResponseCacheStep\
AttachmentNotAllowedReq
You can only attach the Response Cache policy once in the request path. For example, you can't place it in both the Request PreFlow and PostFlow.
ResponseCacheStep\
AttachmentNotAllowedResp
You can only attach the Response Cache policy once in the response path. For example, you can't place it in both the Response PreFlow and PostFlow.
CannotDeleteStepDefinition You must detatch the policy definition from the proxy flows before you can delete the policy.
CacheNotFound The cache specified in the <CacheResource> element does not exist.

Fault variables

N/A

Example error response

N/A

OAuthV2 policy

This section describes the error messages and flow variables that are set when this policy triggers an error. This information is important to know if you are developing fault rules for a proxy. To learn more, see What you need to know about policy errors and Handling faults.

Error code prefix

steps.oauth.v2 (What's this?)

Runtime errors

These errors can occur when the policy executes. The error names shown below are the strings that are assigned to the fault.name variable when an error occurs. See the Fault variables section below for more details.

Error name HTTP status Cause Thrown by operations
InvalidClientIdentifier 500

This error name is returned when the <GenerateResponse> property of the policy is set to false and the client ID sent in the request is invalid. Check to be sure you are using the correct client key and secret values for the Developer App associated with your proxy. Typically, these values are sent as a Base64 encoded Basic Authorization header.

Note: In this situation, this error used to be called invalid_client. It is recommended that you change existing fault rule conditions to catch both the invalid_client and InvalidClientIdentifier names. See the 16.09.21 Release Notes for more information and an example.

GenerateAccessToken
RefreshAccessToken

invalid_client 401

This error name is returned when the <GenerateResponse> property of the policy is set to true and and the client ID sent in the request is invalid. Check to be sure you are using the correct client key and secret values for the Developer App associated with your proxy. Typically, these values are sent as a Base64 encoded Basic Authorization header.

Note: It is recommended that you change existing fault rule conditions to catch both the invalid_client and InvalidClientIdentifier names. See the 16.09.21 Release Notes for more information and an example.

GenerateAccessToken
RefreshAccessToken
invalid_request 400 This error name is used for multiple different kinds of errors, typically for missing or incorrect parameters sent in the request. If <GenerateResponse> is set to false, use fault variables (described below) to retrieve details about the error, such as the fault name and cause. GenerateAccessToken
GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant
RefreshAccessToken
invalid_access_token 401 The access token sent from the client is invalid. VerifyAccessToken
InvalidAccessToken 401 The authorization header does not have the word "Bearer", which is required. For example: Authorization: Bearer your_access_token VerifyAccessToken
apiresource_doesnot_exist 401 The requested resource does not exist any of the API products associated with the access token. VerifyAccessToken
FailedToResolveToken 500 The policy expected to find a token in a variable specified in the <Tokens> element, but the variable could not be resolved.

ValidateToken
InvalidateToken

FailedToResolveClientId 500 The policy expected to find the Client ID in a variable specified in the <ClientId> element, but the variable could not be resolved. GenerateAccessToken
GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant
RefreshAccessToken
FailedToResolveAccessToken 500 The policy expected to find an access token in a variable specified in the <AccessToken> element, but the variable could not be resolved. GenerateAccessToken
FailedToResolveRefreshToken 500 The policy expected to find a refresh token in a variable specified in the <RefreshToken> element, but the variable could not be resolved. RefreshAccessToken
FailedToResolveAuthorizationCode 500 The policy expected to find an authorization code in a variable specified in the <Code> element, but the variable could not be resolved. GenerateAuthorizationCode
UnSupportedGrantType 500

The client specified a grant type that is unsupported by the policy (not listed in the <SupportedGrantTypes> element).

Note: There is currently a bug where unsupported grant type errors are not thrown correctly. If an unsupported grant type error occurs, the proxy does not enter the Error Flow, as expected.

GenerateAccessToken
GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant
RefreshAccessToken
InvalidTokenType 500 The <Tokens>/<Token> element requires you to specify the token type (for example, refreshtoken). If the client passes the wrong type, this error is thrown. ValidateToken
InvalidateToken
InvalidAPICallAsNo\
ApiProductMatchFound
401

The API proxy is not in the Product associated with the access token.

Tips: Be sure that the product assoicated with the access token is configured correctly. For example, if you use wildcards in resource paths, be sure the wildcards are being used correctly. See Create API products for details.

See also this Apigee Community post for more guidance on causes for this error. 

VerifyAccessToken
InsufficientScope 403 The access token presented in the request has a scope that does not match the scope specified in the verify access token policy. To learn about scope, see Working with OAuth2 scopes. VerifyAccessToken
access_token_expired 401 The access token is expired. VerifyAccessToken
access_token_not_approved 401 The access token was revoked. VerifyAccessToken
InvalidParameter 500 The policy must specify either an access token or an authorization code, but not both. GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant
MissingParameter 500 The response type is token, but no grant types are specified. GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name Cause
InvalidValueForExpiresIn

For the <ExpiresIn> element, valid values are positive integers and -1.

InvalidValueForRefreshTokenExpiresIn For the <RefreshTokenExpiresIn> element, valid values are positive integers and -1.
InvalidGrantType An invalid grant type is specified in the <SupportedGrantTypes> element. See the policy reference for a list of valid types.
ExpiresInNotApplicableForOperation Be sure that the operations specified in the <Operations> element support expiration. For example, the VerifyToken operation does not.
RefreshTokenExpiresInNotApplicableForOperation Be sure that the operations specified in the <Operations> element support refresh token expiration. For example, the VerifyToken operation does not.
GrantTypesNotApplicableForOperation Be sure that the grant types specified in <SupportedGrantTypes> are supported for the specified operation.
OperationRequired

You must specify an operation in this policy using the <Operation> element.

Note: If the <Operation> element is missing, the UI throws a schema validation error.

InvalidOperation

You must specify a valid operation in this policy using the <Operation> element.

Note: If the <Operation> element is invalid, the UI throws a schema validation error.

TokenValueRequired You must specify a token <Token> value in the <Tokens> element.

Fault variables

These variables are set when this policy triggers an error at runtime.

You an use these variables to create Fault Rule conditions. These variables are populated when an error occurs if <GenerateResponse> is set to false. If <GenerateResponse> is true, the policy returns a response to the client immediately if an error occurs -- the error flow is skipped and these variables are not populated. For more information, see What you need to know about policy errors.

Variables set (Learn more) Where Example
[prefix].[policy_name].failed The [prefix] is oauthV2.
The [policy_name] is the name of the policy that threw the error.
oauthV2.GenerateAccesstoken.failed = true
[prefix].[policy_name].fault.name The [prefix] is oauthV2.
The [policy_name] is the name of the policy that threw the error.

oauthV2.GenerateAccesstoken.fault.name = invalid_request

Note: For the VerifyAccessToken operation, the fault name includes this suffix: keymanagement.service For example: keymanagement.service.invalid_access_token

[prefix].[policy_name].fault.cause The [prefix] is oauthV2.
The [policy_name] is the name of the policy that threw the error.
oauthV2.GenerateAccesstoken.cause = Required param : grant_type
fault.name = [error_name] [error_name] is the specific error name to check for as listed in the table above. fault.name = "invalid_request"

Example error response

These responses are sent back to the client if the <GenerateResponse> element is true.

For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

If <GenerateResponse> is true, the policy returns errors in this format for operations that generate tokens and codes. For a complete list, see see OAuth HTTP error response reference.

{"ErrorCode" : "invalid_client", "Error" :"ClientId is Invalid"}

If <GenerateResponse> is true, the policy returns errors in this format for verify and validate operations. For a complete list, see see OAuth HTTP error response reference.

{  
   {  
      "fault":{  
         "faultstring":"Invalid Access Token",
         "detail":{  
            "errorcode":"keymanagement.service.invalid_access_token"
         }
      }
   }

Example fault rule

<FaultRule name=OAuthV2 Faults">
    <Step>
        <Name>AM-InvalidClientResponse</Name>
        <Condition>(fault.name = "invalid_client") OR (fault.name = "InvalidClientIdentifier")</Condition>
    </Step>
    <Step>
        <Name>AM-InvalidTokenResponse</Name>
        <Condition>(fault.name = "invalid_access_token")</Condition>
    </Step>
    <Condition>(oauthV2.failed = true) </Condition>
</FaultRule>

Get OAuthV2 Info policy

This section describes the error messages and flow variables that are set when this policy triggers an error. This information is important to know if you are developing fault rules for a proxy. To learn more, see What you need to know about policy errors and Handling faults.

Error code prefix

steps.oauth.v2 (What's this?)

Runtime errors

These errors can occur when the policy executes. The error names shown below are the strings that are assigned to the fault.name variable when an error occurs. See the Fault variables section below for more details.

Error name HTTP status Cause
invalid_access_token 500 The access token sent to the policy is invalid.
access_token_expired 500 The access token sent to the policy is expired.
invalid_refresh_token 500 The refresh token sent to the policy is invalid.
expired_access_token 500 The access token sent to the policy is expired.
refresh_token_expired 500 The refresh token sent to the policy is expired.
invalid_client-invalid_client_id 500 The client ID sent to the policy is invalid.
invalid_request-authorization_code_invalid 500 The authorization code sent to the policy is invalid.
authorization_code_expired 500 The authorization code sent to the policy is expired.

Deployment errors

Refer to the message reported in the UI for information about deployment errors.

Fault variables

These variables are set when this policy triggers an error at runtime.

You an use these variables to create Fault Rule conditions. For more information, see What you need to know about policy errors.

Variables set (Learn more) Where Example
[prefix].[policy_name].failed The [prefix] is oauthV2.
The [policy_name] is the name of the policy that threw the error.
oauthV2.GetTokenInfo.failed = true
[prefix].[policy_name].fault.name The [prefix] is oauthV2.
The [policy_name] is the name of the policy that threw the error.

oauthV2.GetTokenInfo.fault.name = invalid_client-invalid_client_id

[prefix].[policy_name].fault.cause The [prefix] is oauthV2.
The [policy_name] is the name of the policy that threw the error.
oauthV2.GetTokenInfo.cause = ClientID is Invalid
fault.name = [error_name] [error_name] is the specific error name to check for as listed in the table above. fault.name = "invalid_client-invalid_client_id"

Example error response

{  
   "fault":{  
      "faultstring":"ClientId is Invalid",
      "detail":{  
         "errorcode":"keymanagement.service.invalid_client-invalid_client_id"
      }
   }
}

Example fault rule

<FaultRule name="OAuthV2 Faults">
    <Step>
        <Name>AM-InvalidClientIdResponse</Name>
    </Step>
    <Condition>(fault.name = "invalid_client-invalid_client_id")</Condition>
</FaultRule>

Set OAuthV2 Info policy

This section describes the error messages and flow variables that are set when this policy triggers an error. This information is important to know if you are developing fault rules for a proxy. To learn more, see What you need to know about policy errors and Handling faults.

Error code prefix

steps.oauth.v2 (What's this?)

Runtime errors

These errors can occur when the policy executes. The error names shown below are the strings that are assigned to the fault.name variable when an error occurs. See the Fault variables section below for more details.

Error name HTTP status Cause
invalid_access_token 500 The access token sent to the policy is invalid.
expired_access_token 500 The access token sent to the policy is expired.

Deployment errors

Refer to the message reported in the UI for information about deployment errors.

Fault variables

These variables are set when this policy triggers an error at runtime.

You an use these variables to create Fault Rule conditions. For more information, see What you need to know about policy errors.

Variables set (Learn more) Where Example
[prefix].[policy_name].failed The [prefix] is oauthV2.
The [policy_name] is the name of the policy that threw the error.
oauthV2.SetTokenInfo.failed = true
[prefix].[policy_name].fault.name The [prefix] is oauthV2.
The [policy_name] is the name of the policy that threw the error.

oauthV2.SetTokenInfo.fault.name = invalid_access_token

[prefix].[policy_name].fault.cause The [prefix] is oauthV2.
The [policy_name] is the name of the policy that threw the error.
oauthV2.SetTokenInfo.cause = Invalid Access Token
fault.name = [error_name] [error_name] is the specific error name to check for as listed in the table above. fault.name = "invalid_access_token"

Example error response

{
  "fault": {
    "faultstring": "Invalid Access Token",
    "detail": {
      "errorcode": "keymanagement.service.invalid_access_token"
    }
  }
}

Example fault rule

<FaultRule name=SetOAuthV2Info Faults">
    <Step>
        <Name>AM-InvalidTokenResponse</Name>
        <Condition>(fault.name = "invalid_access_token")</Condition>
    </Step>
    <Condition>(oauthV2.failed = true) </Condition>
</FaultRule>

Delete OAuthV2 Info policy

This section describes the error messages and flow variables that are set when this policy triggers an error. This information is important to know if you are developing fault rules for a proxy. To learn more, see What you need to know about policy errors and Handling faults.

Error code prefix

steps.oauth.v2 (What's this?)

Runtime errors

These errors can occur when the policy executes. The error names shown below are the strings that are assigned to the fault.name variable when an error occurs. See the Fault variables section below for more details.

Error name HTTP status Cause
invalid_access_token 500 The access token sent to the policy is invalid.
invalid_request-authorization_code_invalid 500 The authorization code sent to the policy is invalid.

Deployment errors

Refer to the message reported in the UI for information about deployment errors.

Fault variables

These variables are set when this policy triggers an error at runtime.

You an use these variables to create Fault Rule conditions. For more information, see What you need to know about policy errors.

Variables set (Learn more) Where Example
[prefix].[policy_name].failed The [prefix] is oauthV2.
The [policy_name] is the name of the policy that threw the error.
oauthV2.DeleteTokenInfo.failed = true
[prefix].[policy_name].fault.name The [prefix] is oauthV2.
The [policy_name] is the name of the policy that threw the error.

oauthV2.DeleteTokenInfo.fault.name = invalid_access_token

[prefix].[policy_name].fault.cause The [prefix] is oauthV2.
The [policy_name] is the name of the policy that threw the error.
oauthV2.DeleteTokenInfo.cause = Invalid Access Token
fault.name = [error_name] [error_name] is the specific error name to check for as listed in the table above. fault.name = "invalid_access_token"

Example error response

{
  "fault": {
    "faultstring": "Invalid Access Token",
    "detail": {
      "errorcode": "keymanagement.service.invalid_access_token"
    }
  }
}

Example fault rule

<FaultRule name="DeleteOAuthV2Info_Faults">
    <Step>
        <Name>AM-InvalidTokenResponse</Name>
    </Step>
    <Condition>(fault.name = "invalid_access_token")</Condition>
</FaultRule>

OAuth v1.0a policy

The OAuthV1 Policy type defines the following error codes.

For OAuth-related HTTP error codes, see OAuth HTTP error response reference.

Error Code Message
AppKeyNotResolved Could not resolve the app key with variable {0}
ConsumerKeyNotResolved Could not resolve the consumer key with variable {0}
RequestTokenNotResolved Could not resolve the request token with the variable {0}
AccessTokenNotResolved Could not resolve the access token with the variable {0}
ResponseGenerationError Error while generating response : {0}
UnableToDetermineOperation Unable to determine an operation for stepDefinition {0}
UnableToResolveOAuthConfig Unable to resolve the OAuth configuration for {0}
AtLeastOneParamRequired At least one of AccessToken, RequestToken or ConsumerKey must be specified in stepDefinition {0}
SpecifyValueOrRefReqToken Specify Request Token as value or ref in stepDefinition {0}
SpecifyValueOrRefAccToken Specify Access Token as value or ref in stepDefinition {0}
SpecifyValueOrRefConKey Specify Consumer Key as value or ref in stepDefinition {0}
SpecifyValueOrRefAppKey Specify App Key as value or ref in stepDefinition {0}
ExpiresInNotApplicableForOperation ExpiresIn element is not valid for operation {0}
InvalidValueForExpiresIn Invalid value for ExpiresIn element for operation {0}
FailedToFetchApiProduct Failed to fetch api product for key {0}
InvalidTokenType Valid token types : {0}, Invalid toke type {1} in stepDefinition {2}
TokenValueRequired Token value is required in stepDefinition {0}
FailedToResolveRealm Failed to resolve realm {0}

Get OAuthV1 Info policy

No error codes are specified for the Get OAuth v1.0a Info policy.

 

Delete OAuthV1 Info policy

On success, the policy returns a 200 status.

On failure, the policy returns 404 and output similar to the following (depending on whether you are deleting an access token, request token, or verifier.):

HTTP/1.1 404 Not Found
Content-Type: application/json
Content-Length: 144
Connection: keep-alive

{"fault":{"faultstring":"Invalid Access Token","detail":{"errorcode":"keymanagement.service.invalid_request-access_token_invalid"}}}


Python Script policy

No error codes are specified for the Python Script policy.

Quota policy

This section describes the error messages and flow variables that are set when this policy triggers an error. This information is important to know if you are developing fault rules for a proxy. To learn more, see What you need to know about policy errors and Handling faults.

Error code prefix

policies.ratelimit (What's this?)

Runtime errors

These errors can occur when the policy executes.

Error name HTTP status Occurs when
QuotaViolation 500 The quota limit is exceeded.
InvalidMessageWeight 500 The message weight value must be an integer.
InvalidQuotaInterval 500 The quota interval must be an integer.
FailedToResolveQuota\
IntervalReference
500 See fault string. 
FailedToResolveQuota\
IntervalTimeUnitReference
500 See fault string. 
InvalidQuotaTimeUnit 500 If no default value is specified, then the specified variable reference must be set to minute, hour, day, week, or month.

Deployment errors

Error name Occurs when
InvalidQuotaInterval The quota interval must be an integer.
InvalidQuotaTimeUnit If specified, default value must be set to minute, hour, day, week, or month.
InvalidQuotaType See fault string. Valid types are listed in the documentation.
InvalidStartTime See fault string.
StartTimeNotSupported See fault string and Quota policy documentation for more information about <StartTime>.

Other errors

Error name Occurs when
InvalidTimeUnitForDistributedQuota See fault string.
InvalidSynchronizeIntervalForAsyncConfiguration See fault string.
InvalidSynchronizeMessageCountForAsyncConfiguration See fault string.
InvalidAsynchronizeConfigurationForSynchronousQuota See fault string.

Fault variables

These variables are set when this policy triggers an error. For more information, see What you need to know about policy errors.

Variables set (Learn more) Where Example
[prefix].[policy_name].failed The fault variable [prefix] is ratelimit.
The [policy_name] is the name of the policy that threw the error.
ratelimit.QT-QuotaPolicy.failed = true
fault.[error_name] [error_name] = The specific error name to check for as listed in the table above. fault.name Matches "QuotaViolation"

Example error response

For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

{  
   "fault":{  
      "detail":{  
         "errorcode":"policies.ratelimit.QuotaViolation"
      },
      "faultstring":"Rate limit quota violation. Quota limit  exceeded. Identifier : _default"
   }
}

Example fault rule

<FaultRules>
    <FaultRule name="Quota Errors">
        <Step>
            <Name>JavaScript-1</Name>
            <Condition>(fault.name Matches "QuotaViolation") </Condition>
        </Step>
        <Condition>ratelimit.Quota-1.failed=true</Condition>
    </FaultRule>
</FaultRules>

Reset Quota policy

The Reset Quota policy type defines the following error codes. For guidance on handling errors, see Handling faults.

Error Code Message
InvalidRLPolicyDefinition Invalid rate limit policy {0}
NoRLPolicy Quota policy {0} is not attached.
InvalidCount Invalid count value {0} for identifier {1} in {2}
FailedToResolveAllowCountRef Failed to resolve allow count reference {0} for identifier {1} in {2}

Raise Fault policy

This section describes the error messages and flow variables that are set when this policy triggers an error. This information is important to know if you are developing fault rules to handle errors. To learn more, see What you need to know about policy errors and Handling faults.

Error code prefix

steps.raisefault (What's this?)

Runtime errors

These errors can occur when the policy executes.

Error name HTTP status Cause
RaiseFault 500 See fault string.

Deployment errors

None.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables set (Learn more) Where Example
[prefix].[policy_name].failed The [prefix] is raisefault.
The [policy_name] is the name of the policy that threw the error.
raisefault.RF-ThrowError.failed = true
fault.[error_name] [error_name] = The specific error name to check for as listed in the table above. fault.name = "RaiseFault"

Example error response

For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

{  
   "fault":{  
      "detail":{  
         "errorcode":"steps.raisefault.RaiseFault"
      },
      "faultstring":"Raising fault. Fault name: [name]"
   }
}

Example fault rule

<FaultRule name="RaiseFault">
    <Step>
        <Name>RF-ThrowError</Name>
        <Condition>(fault.name Matches "RaiseFault") </Condition>
    </Step>
</FaultRule>

Regular Expression Protection policy

The RegularExpressionProtection policy type defines the following error codes. If you want to capture an error and raise your own custom error, set the continueOnError="true" attribute on the policy root element, and see Handling faults for more information.

Error Code Message
NothingToEnforce RegularExpressionProtection {0}: at least one of URIPath, QueryParam, Header, FormParam, XMLPayload, JSONPayload is mandatory
NoPatternsToEnforce RegularExpressionProtection {0}: No patterns to enforce in {1}
EmptyXPathExpression RegularExpressionProtection {0}: Empty XPath expression
EmptyJSONPathExpression RegularExpressionProtection {0}: Empty JSONPath expression
DuplicatePrefix RegularExpressionProtection {0}: Duplicate prefix {1}
NONEmptyPrefixMappedToEmptyURI RegularExpressionProtection {0}: Non-empty prefix {1} cannot be mapped to empty uri
ThreatDetected Regular Expression Threat Detected in {0}: regex: {1} input: {2}
ExecutionFailed Failed to execute the RegularExpressionProtection StepDefinition {0}. Reason: {1}
VariableResolutionFailed Failed to resolve variable {0}
NonMessageVariable Variable {0} does not resolve to a Message
SourceMessageNotAvailable {0} message is not available for RegularExpressionProtection StepDefinition {1}
InvalidRegularExpression RegularExpressionProtection {0}: Invalid Regular Expression {1}, Context {2}
InstantiationFailed Failed to instantiate the RegularExpressionProtection StepDefinition {0}
CannotBeConvertedToNodeset RegularExpressionProtection {0}: Result of xpath {1} cannot be converted to nodeset. Context {2}
XPathCompilationFailed RegularExpressionProtection {0}: Failed to compile xpath {1}. Context {2}
JSONPathCompilationFailed RegularExpressionProtection {0}: Failed to compile jsonpath {1}. Context {2}

SOAP Message Validation policy

This policy returns the following error codes and error messages in error responses. For guidance on handling errors, see Handling faults

Error Code Message
InvalidResourceType InvalidResourceType MessageValidation {0}: Invalid Resource Type {1}. It should be xsd or wsdl. Context {2}
ResourceCompileFailed ResourceCompileFailed MessageValidation {0}: Failed to compile resource {1}. Context {2}
RootElementNameUnspecified RootElementNameUnspecified MessageValidation {0}: RootElement name is not specified
InvalidRootElementName InvalidRootElementName MessageValidation {0}: RootElement name {1} is invalid
NonMessageVariable NonMessageVariable Variable {0} does not resolve to a Message
SourceMessageNotAvailable SourceMessageNotAvailable {0} message is not available for MessageValidation: {1}
NoElements Resource "{0}" has no element definitions
Failed MessageValidation {0} failed with reason: "{1}"

SAML Assertion policy

No error codes are specified for the SAML Assertion policy.

Service Callout policy

This section describes the error messages and flow variables that are set when this policy triggers an error. This information is important to know if you are developing fault rules for a proxy. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Error name HTTP status Cause
RequestVariableNotMessageType 500 The Request variable specified in the policy is not of type Message. For example, if it's a string or other non-message type, you'll see this error.
RequestVariableNotRequest\
MessageType
500 The Request variable specified in the policy is not of type Request Message. For example, if it's a Response type, you'll see this error.
ExecutionFailed 500

This error can occur when:

  • the policy is asked to handle input that is malformed or otherwise invalid.
  • the backend target service returns an error status (by default, 4xx or 5xx).
InvalidExecutionState 500  

 

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name Occurs when
URLMissing The <URL> element inside <HTTPTargetConnection> is missing or empty.
ConnectionInfoMissing This error happens if the policy does not have an <HTTPTargetConnection> or <LocalTargetConnection> element.
InvalidTimeoutValue This error happens if the <Timeout> value is negative or zero.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables set (Learn more) Where Example
[prefix].[policy_name].failed

The [prefix] is servicecallout.
[policy_name]: The name of the policy to check.

servicecallout.SC-GetUserData.failed = true
fault.[error_name] [error_name] = The specific error name to check for as listed in the table above. fault.name = "RequestVariableNotMessageType"

Example error response

For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

{  
   "fault":{  
      "detail":{  
         "errorcode":"steps.servicecallout.RequestVariableNotMessageType"
      },
      "faultstring":"ServiceCallout[ServiceCalloutGetMockResponse]: 
            request variable data_str value is not of type Message"
   }
}

Example fault rule

<FaultRule name="RequestVariableNotMessageType">
    <Step>
        <Name>AM-RequestVariableNotMessageType</Name>
    </Step>
    <Condition>(fault.name = "RequestVariableNotMessageType")</Condition>
</FaultRule>

Spike Arrest policy

This section describes the error messages and flow variables that are set when this policy triggers an error. This information is important to know if you are developing fault rules for a proxy. To learn more, see What you need to know about policy errors and Handling faults.

Error code prefix

policies.ratelimit (What's this?)

Runtime errors

These errors can occur when the policy executes.

Error name HTTP status Occurs when
SpikeArrestViolation 500 The rate limit is exceeded.
InvalidMessageWeight 500 The message weight value must be an integer.
FailedToResolveSpikeArrestRate 500 The referenced variable used to specify the rate can't be resolved.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name Occurs when
InvalidAllowedRate Valid values are [int]ps or [int]pm.

Other errors

Error name Occurs when
ErrorLoadingProperties See fault string.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables set (Learn more) Where Example
[prefix].[policy_name].failed The fault variable [prefix] is ratelimit.
The [policy_name] is the name of the policy that threw the error.
ratelimit.SA-SpikeArrestPolicy.failed = true
fault.[error_name] [error_name] = The specific error name to check for as listed in the table above. fault.name Matches "SpikeArrestViolation"

Example error response

For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

{  
   "fault":{  
      "detail":{  
         "errorcode":"policies.ratelimit.SpikeArrestViolation"
      },
      "faultstring":"Spike arrest violation. Allowed rate : 10ps"
   }
}

Example fault rule

<FaultRules>
    <FaultRule name="Spike Arrest Errors">
        <Step>
            <Name>JavaScript-1</Name>
            <Condition>(fault.name Matches "SpikeArrestViolation") </Condition>
        </Step>
        <Condition>ratelimit.Spike-Arrest-1.failed=true</Condition>
    </FaultRule>
</FaultRules>

Statistics Collector policy

This section describes the error messages and flow variables that are set when this policy triggers an error. This information is important to know if you are developing fault rules for a proxy. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

Note.

Deployment errors

Error name Fault string HTTP status Occurs when
UnsupportedDatatype StatisticsCollection [collection]: Datatype [type] is unsupported . Context [context] N/A See fault string.
InvalidName StatisticsCollection: Name: [name] conflicts with system defined variables. Context [context] N/A See fault string.
DatatypeMissing StatisticsCollection [name]: Datatype of [type] is missing. Context [context] N/A See fault string. See the policy doc for more information.

 

Fault variables

None.

Verify API Key policy

This section describes the error messages and flow variables that are set when this policy triggers an error. This information is important to know if you are developing fault rules for a proxy. To learn more, see What you need to know about policy errors and Handling faults.

Error code prefix (What's this?)

The errorcode prefix is oauth.v2 for the errors FailedToResolveAPIKey, InvalidApiKey, and InvalidApiKeyForGivenResource.

The prefix is keymanagement.service for the errors CompanyStatusNotActive, DeveloperStatusNotActive, and invalid_client-app_not_approved. See the Example error responses at the end of this section.

Runtime errors

These errors can occur when the policy executes.

Error name HTTP status Cause
CompanyStatusNotActive 401 The Company associated with the Developer App that has the API key you are using has an inactive status. When a Company's status is set to inactive,  you cannot access the developers or apps associated with that Company. An org admin can change a Company's status using the management API. See Set the Status of a Company.
DeveloperStatusNotActive 401

The developer who created the the Developer App that has the API key you are using has an inactive status. When an App Developer's status is set to inactive, any Developer Apps created by that developer are deactivated. An admin user with appropriate permissions (such as Organization Administrator) can change a developer's status in the following ways:

FailedToResolveAPIKey 401 The policy expects to find the API key in a variable that is specified in the policy's <APIKey> element. This error arises when the expected variable does not exist (it cannot be resolved).
InvalidApiKey 401 An API key was received by Edge, but it is invalid. When Edge looks up the key in its database, it must exactly match the on that was sent in the request. If the API worked previously, make sure the key was not regenerated. If the key was regenerated, you will see this error if you try to use the old key. For details, see Register apps and manage API keys.
InvalidApiKeyForGivenResource 401 An API key was received by Edge, and it is valid; however, it does not match an approved key in the Developer App associated with your API proxy through a Product.
invalid_client-app_not_approved 401 The Developer App associated with the API key is revoked.  A revoked app cannot access any API products and cannot invoke any API managed by Apigee Edge. An org admin can change the status of a Developer App using the management API. See Approve or Revoke Developer App.

 

Currently Edge does not report the ApiKeyNotApproved error accurately. Instead, if a key is not approved (its status is set to "revoked" or "pending"), you will get the FailedToResolveAPIKey error instead. For more information and a possible workaround, see this post on the Apigee Community

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name Cause
SpecifyValueOrRefApiKey The <APIKey> element does not have a value or key specified.

 

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables set (Learn more) Where Example
[prefix].[policy_name].failed

The fault variable [prefix] is oauthV2.

The [policy_name] is the name of the policy that threw the error.
oauthV2.VK-VerifyAPIKey.failed = true
fault.[error_name] [error_name] = The specific error name to check for as listed in the table above. fault.name Matches "FailedToResolveAPIKey"

Example error responses

For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

{  
   "fault":{  
      "faultstring":"Invalid ApiKey",
      "detail":{  
         "errorcode":"oauth.v2.InvalidApiKey"
      }
   }
}
{  
   "fault":{  
      "detail":{  
         "errorcode":"keymanagement.service.DeveloperStatusNotActive"
      },
      "faultstring":"Developer Status is not Active"
   }
}

Example fault rule

<FaultRule name="FailedToResolveAPIKey">
    <Step>
        <Name>AM-FailedToResolveAPIKey</Name>
    </Step>
    <Condition>(fault.name Matches "FailedToResolveAPIKey") </Condition>
</FaultRule>

XML Threat Protection policy

This section describes the error messages and flow variables that are set when this policy triggers an error. This information is important to know if you are developing fault rules for a proxy. To learn more, see What you need to know about policy errors and Handling faults.

Error code prefix

steps.xmlthreatprotection (What's this?)

Runtime errors

These errors can occur when the policy executes.

Error name HTTP status Cause
NodeDepthExceeded 500 See fault string.
AttrCountExceeded 500 See fault string.
ChildCountExceeded 500 See fault string.
NSCountExceeded 500 See fault string.
ElemNameExceeded 500 See fault string.
AttrNameExceeded 500 See fault string.
AttrValueExceeded 500 See fault string.
NSPrefixExceeded 500 See fault string.
NSURIExceeded 500 See fault string.
PITargetExceeded 500 See fault string.
PIDataExceeded 500 See fault string.
CommentExceeded 500 See fault string.
TextExceeded 500 See fault string.
SourceUnavailable 500 See fault string.
NonMessageVariable 500 See fault string.
ExecutionFailed 500 See fault string.

Deployment errors

None.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables set (Learn more) Where Example
[prefix].[policy_name].failed The [prefix] is xmlattack.
The [policy_name] is the name of the policy that threw the error.
xmlattack.XPT-SecureRequest.failed = true
fault.[error_name] [error_name] = The specific error name to check for as listed in the table above. fault.name Matches "SourceUnavailable"

Example error response

For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

{
  "fault": {
    "faultstring": "XMLThreatProtection[XPT-SecureRequest]: Execution failed. reason: XMLThreatProtection[XTP-SecureRequest]: Exceeded object entry name length at line 2",
    "detail": {
      "errorcode": "steps.xmlthreatprotection.ExecutionFailed"
    }
  }
}

Example fault rule

<FaultRule name="XML Threat Protection Policy Faults">
    <Step>
        <Name>AM-CustomErrorResponse</Name>
        <Condition>(fault.name Matches "ExecutionFailed") </Condition>
    </Step>
    <Condition>(xmlattack.XPT-SecureRequest.failed = true) </Condition>
</FaultRule>

XML to JSON policy

This section describes the error messages and flow variables that are set when this policy triggers an error. This information is important to know if you are developing fault rules for a proxy. To learn more, see What you need to know about policy errors and Handling faults.

Error code prefix

steps.xmltojson (What's this?)

Runtime errors

These errors can occur when the policy executes.

Error name HTTP status Cause
EitherOptionOrFormat 500 See the fault string.
UnknownFormat 500 See the fault string.
FormatUnavailable 500 See the fault string.
SourceUnavailable 500 The variable specified in the <Source> element has to exist.
ExecutionFailed 500 See the fault string. Be sure the incoming message contains valid XML.
InvalidSourceType 500 See the fault string.
InCompatibleTypes 500 See the fault string.
OutputVariableIsNotAvailable 500 See the fault string.

Deployment errors

None.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables set (Learn more) Where Example
[prefix].[policy_name].failed The [prefix] is xmltojson.
The [policy_name] is the name of the policy that threw the error.
xmltojson.XMLtoJSON-1.failed = true
fault.[error_name] [error_name] = The specific error name to check for as listed in the table above. fault.name Matches "SourceUnavailable"

Example error response

For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

{
  "fault": {
    "faultstring": "XMLToJSON[XMLtoJSON-1]: Source xyz is not available",
    "detail": {
      "errorcode": "steps.xml2json.SourceUnavailable"
    }
  }
}

Example fault rule

<FaultRule name="XML to JSON Faults">
    <Step>
        <Name>AM-SourceUnavailableMessage</Name>
        <Condition>(fault.name Matches "SourceUnavailable") </Condition>
    </Step>
    <Step>
        <Name>AM-BadXML</Name>
        <Condition>(fault.name = "ExecutionFailed")</Condition>
    </Step>
    <Condition>(xmltojson.XMLtoJSON-1.failed = true) </Condition>
</FaultRule>

XSL Transform policy

The XSLT policy type defines the following error codes (the numerals represent placeholders for values inserted at runtime):

Error Code Message
XSLSourceMessageNotAvailable {0} message is not available for XSL: {1}
XSLEvaluationFailed Evaluation of XSL {0} failed with reason: "{1}"
XSLVariableResolutionFailed Failed to resolve variable {0}
XSLInvalidResourceType XSL {0}: Resource type must be xsl. Context {1}
XSLEmptyResourceUrl Resource Url cannot be empty in XSL {0}

Help or comments?