Notification Policies

You can define notification policies to limit the use of SMS/voice and email notifications for pairing and authentication.

Parameters for creating/updating notification policies

Property Type Required Mutable Description

Property	Type	Required	Mutable	Description
`cooldownConfiguration`	Object	Optional	Mutable	Include the `cooldownConfiguration` object in the request if you want to specify a period of time that users must wait before requesting an additional notification such as an additional OTP.
`cooldownConfiguration.email`	Object	Required	Mutable	Required if you have included the `cooldownConfiguration` object. Contains the notification cooldown period settings for email notifications.
`cooldownConfiguration.sms`	Object	Required	Mutable	Required if you have included the `cooldownConfiguration` object. Contains the notification cooldown period settings for sms notifications.
`cooldownConfiguration.voice`	Object	Required	Mutable	Required if you have included the `cooldownConfiguration` object. Contains the notification cooldown period settings for voice notifications.
`cooldownConfiguration.whatsApp`	Object	Required	Mutable	Required if you have included the `cooldownConfiguration` object. Contains the notification cooldown period settings for whatsApp notifications.
`cooldownConfiguration.(authentication method).enabled`	Boolean	Required	Mutable	Set to `true` if you want to specify notification cooldown periods for the authentication method. Set to `false` if you don’t want notification cooldown periods for this authentication method.
`cooldownConfiguration.(authentication method).periods`	Array	Required/Optional	Mutable	Required if `cooldownConfiguration.(authentication method).enabled` is `true`. Use the `periods` array to specify the amount of time the user has to wait before requesting another notification such as another OTP. The array should contain three objects: the time to wait before the first retry, the time to wait before the second retry, and the time to wait before any subsequent retries.
`cooldownConfiguration.(authentication method).periods[].duration`	Integer	Required/Optional	Mutable	Required if `cooldownConfiguration.(authentication method).enabled` is `true`. Used in conjunction with `timeUnit` to specify the waiting period. Minimum is ten seconds, maximum is ten minutes.
`cooldownConfiguration.(authentication method).periods[].timeUnit`	String	Required/Optional	Mutable	Required if `cooldownConfiguration.(authentication method).enabled` is `true`. Used in conjunction with `duration` to specify the waiting period. Can be set to `SECONDS` or `MINUTES`.
`cooldownConfiguration.(authentication method).groupBy`	String	Optional	Mutable	Since bad actors may try to target multiple users at a single email address or phone number, by default the cooldown settings (both waiting period and maximum retries) are applied to the email address or phone number. If you want the settings to be applied at the single-user level for the address/number, include the `groupBy` parameter in the request and set it to `USER_ID`.
`cooldownConfiguration.(authentication method).resendLimit`	Integer	Required/Optional	Mutable	Required if `cooldownConfiguration.(authentication method).enabled` is `true`. The maximum number of requests that a user can send to receive another notification, such as another OTP, before they are blocked for 30 minutes.
`countryLimit`	Object	Optional	Mutable	You can use the `countryLimit` object to limit the countries where you can send SMS and voice notifications.
`countryLimit.type`	String	Required/Optional	Mutable	Determines the kind of limitation being defined. The possible values are * NONE * ALLOWED - allows SMS/Voice notifications only for the countries specified with `countryLimit.countries` * DENIED - denies SMS/Voice notifications for the countries specified with `countryLimit.countries`
`countryLimit.deliveryMethods`	Array	Optional	Mutable	The delivery methods that the defined limitation should be applied to. Content of the array can be `SMS`, `Voice`, or both. If the parameter is not provided, the default is SMS and Voice.
`countryLimit.countries`	Array	Required/Optional	Mutable	The countries where the specified methods should be allowed or denied. Use the two-letter country codes from ISO 3166-1.
`createdAt`	Date	N/A	Read-only	The date and time the notification policy was created.
`default`	Boolean	Optional	Mutable	Indication of whether this policy is the default notification policy for the environment. If the parameter is not provided, the value used is `false`
`environment.id`	String	N/A	Read-only	The ID of the PingOne environment that contains the notification policy.
`id`	String	N/A	Read-only	The ID generated for the notification policy when it was created.
`name`	String	Required	Mutable	The name to use for the notification policy. Must be unique among the notification policies in the environment.
`providerConfiguration`	Object	Optional	Mutable	If you have defined more than one custom provider, you can use the `providerConfiguration` object to specify the provider preference to use for different countries and for the different methods (SMS and Voice).
`providerConfiguration.conditions`	Array	Optional	Mutable	Each element in the `conditions` array represents the provider fallback order to use for a specific group of countries for the specified methods (SMS and/or Voice). Note that in addition to any country-specific orders specified, the array must contain a fallback order without the `countries` array in the object. This order is used for all countries that were not specified in one of the other fallback orders defined.
`providerConfiguration.conditions[].deliveryMethods`	Array	Optional	Mutable	The authentication methods that the fallback order should be used for. The array can contain `VOICE`, `SMS`, or both.
`providerConfiguration.conditions[].countries`	Array	Optional	Mutable	The countries for which the fallback order should be used. Use the two-letter country codes from ISO 3166-1.
`providerConfiguration.conditions[].fallbackChain`	Array	Optional	Mutable	An array containing the IDs of the defined custom providers, in the order that they should be used if available.
`providerConfiguration.conditions[].fallbackChain.id`	String	Optional	Mutable	The ID of one of the defined custom providers. This is the ID that is returned when you create the provider using the `phoneDeliverySettings` endpoint or when you run the GET request with that endpoint to retrieve the details of all the providers.
`quotas`	Array	Required	Mutable	Collection of objects that define the SMS/voice and email limits. Each object contain the following elements: `type`, `deliveryMethods`, `total`. Note that instead of `total`, you can use the pair of fields: `claimed` and `unclaimed`.
`quotas[].type`	String	Required	Mutable	Specifies whether the limit defined is per-user or per environment. Value must be either `USER` or `ENVIRONMENT`.
`quotas[].deliveryMethods`	Array	Required	Mutable	The delivery methods for which the limit is being defined. The value can be `Email` or `SMS,Voice`. When you use the `SMS`, `Voice` option, it means that the combined total of SMS and voice notifications must be below the limit defined. If you are limiting both email and SMS/voice, each limit should be represented by a different object in the `quotas` array, for example: `"quotas": [{"type": "USER","deliveryMethods": ["SMS","Voice"],"total": 30},{"type": "USER","deliveryMethods": ["Email"],"total": 30}]`
`quotas[].total`	Integer	Required/Optional	Mutable	The maximum number of notifications allowed per day.
`quotas[].claimed`	Integer	Required/Optional	Mutable	The maximum number of notifications that can be received and responded to each day. Used in conjunction with `unclaimed` in place of the single field `total`.
`quotas[].unclaimed`	Integer	Required/Optional	Mutable	The maximum number of notifications that can be received and not responded to each day. Used in conjunction with `claimed` in place of the single field `total`.
`updatedAt`	Date	N/A	Read-only	The date and time the notification policy was last updated.

cooldownConfiguration

Object

Optional

Mutable

Include the cooldownConfiguration object in the request if you want to specify a period of time that users must wait before requesting an additional notification such as an additional OTP.

cooldownConfiguration.email

Object

Required

Mutable

Required if you have included the cooldownConfiguration object. Contains the notification cooldown period settings for email notifications.

cooldownConfiguration.sms

Object

Required

Mutable

Required if you have included the cooldownConfiguration object. Contains the notification cooldown period settings for sms notifications.

cooldownConfiguration.voice

Object

Required

Mutable

Required if you have included the cooldownConfiguration object. Contains the notification cooldown period settings for voice notifications.

cooldownConfiguration.whatsApp

Object

Required

Mutable

Required if you have included the cooldownConfiguration object. Contains the notification cooldown period settings for whatsApp notifications.

cooldownConfiguration.(authentication method).enabled

Boolean

Required

Mutable

Set to true if you want to specify notification cooldown periods for the authentication method. Set to false if you don’t want notification cooldown periods for this authentication method.

cooldownConfiguration.(authentication method).periods

Array

Required/Optional

Mutable

Required if cooldownConfiguration.(authentication method).enabled is true. Use the periods array to specify the amount of time the user has to wait before requesting another notification such as another OTP. The array should contain three objects: the time to wait before the first retry, the time to wait before the second retry, and the time to wait before any subsequent retries.

cooldownConfiguration.(authentication method).periods[].duration

Integer

Required/Optional

Mutable

Required if cooldownConfiguration.(authentication method).enabled is true. Used in conjunction with timeUnit to specify the waiting period. Minimum is ten seconds, maximum is ten minutes.

cooldownConfiguration.(authentication method).periods[].timeUnit

String

Required/Optional

Mutable

Required if cooldownConfiguration.(authentication method).enabled is true. Used in conjunction with duration to specify the waiting period. Can be set to SECONDS or MINUTES.

cooldownConfiguration.(authentication method).groupBy

String

Optional

Mutable

Since bad actors may try to target multiple users at a single email address or phone number, by default the cooldown settings (both waiting period and maximum retries) are applied to the email address or phone number. If you want the settings to be applied at the single-user level for the address/number, include the groupBy parameter in the request and set it to USER_ID.

cooldownConfiguration.(authentication method).resendLimit

Integer

Required/Optional

Mutable

Required if cooldownConfiguration.(authentication method).enabled is true. The maximum number of requests that a user can send to receive another notification, such as another OTP, before they are blocked for 30 minutes.

countryLimit

Object

Optional

Mutable

You can use the countryLimit object to limit the countries where you can send SMS and voice notifications.

countryLimit.type

String

Required/Optional

Mutable

Determines the kind of limitation being defined. The possible values are

* NONE

* ALLOWED - allows SMS/Voice notifications only for the countries specified with countryLimit.countries

* DENIED - denies SMS/Voice notifications for the countries specified with countryLimit.countries

countryLimit.deliveryMethods

Array

Optional

Mutable

The delivery methods that the defined limitation should be applied to. Content of the array can be SMS, Voice, or both. If the parameter is not provided, the default is SMS and Voice.

countryLimit.countries

Array

Required/Optional

Mutable

The countries where the specified methods should be allowed or denied. Use the two-letter country codes from ISO 3166-1.

createdAt

Date

N/A

Read-only

The date and time the notification policy was created.

default

Boolean

Optional

Mutable

Indication of whether this policy is the default notification policy for the environment. If the parameter is not provided, the value used is false

environment.id

String

N/A

Read-only

The ID of the PingOne environment that contains the notification policy.

id

String

N/A

Read-only

The ID generated for the notification policy when it was created.

name

String

Required

Mutable

The name to use for the notification policy. Must be unique among the notification policies in the environment.

providerConfiguration

Object

Optional

Mutable

If you have defined more than one custom provider, you can use the providerConfiguration object to specify the provider preference to use for different countries and for the different methods (SMS and Voice).

providerConfiguration.conditions

Array

Optional

Mutable

Each element in the conditions array represents the provider fallback order to use for a specific group of countries for the specified methods (SMS and/or Voice). Note that in addition to any country-specific orders specified, the array must contain a fallback order without the countries array in the object. This order is used for all countries that were not specified in one of the other fallback orders defined.

providerConfiguration.conditions[].deliveryMethods

Array

Optional

Mutable

The authentication methods that the fallback order should be used for. The array can contain VOICE, SMS, or both.

providerConfiguration.conditions[].countries

Array

Optional

Mutable

The countries for which the fallback order should be used. Use the two-letter country codes from ISO 3166-1.

providerConfiguration.conditions[].fallbackChain

Array

Optional

Mutable

An array containing the IDs of the defined custom providers, in the order that they should be used if available.

providerConfiguration.conditions[].fallbackChain.id

String

Optional

Mutable

The ID of one of the defined custom providers. This is the ID that is returned when you create the provider using the phoneDeliverySettings endpoint or when you run the GET request with that endpoint to retrieve the details of all the providers.

quotas

Array

Required

Mutable

Collection of objects that define the SMS/voice and email limits. Each object contain the following elements: type, deliveryMethods, total. Note that instead of total, you can use the pair of fields: claimed and unclaimed.

quotas[].type

String

Required

Mutable

Specifies whether the limit defined is per-user or per environment. Value must be either USER or ENVIRONMENT.

quotas[].deliveryMethods

Array

Required

Mutable

The delivery methods for which the limit is being defined. The value can be Email or SMS,Voice. When you use the SMS, Voice option, it means that the combined total of SMS and voice notifications must be below the limit defined. If you are limiting both email and SMS/voice, each limit should be represented by a different object in the quotas array, for example:
"quotas": [{"type": "USER","deliveryMethods": ["SMS","Voice"],"total": 30},{"type": "USER","deliveryMethods": ["Email"],"total": 30}]

quotas[].total

Integer

Required/Optional

Mutable

The maximum number of notifications allowed per day.

quotas[].claimed

Integer

Required/Optional

Mutable

The maximum number of notifications that can be received and responded to each day. Used in conjunction with unclaimed in place of the single field total.

quotas[].unclaimed

Integer

Required/Optional

Mutable

The maximum number of notifications that can be received and not responded to each day. Used in conjunction with claimed in place of the single field total.

updatedAt

Date

N/A

Read-only

The date and time the notification policy was last updated.

When you create/update a notification policy, the response also includes the following information:

id - the ID assigned to the notification policy
createdAt - date and time when the policy was created
updatedAt - date and time when the policy was updated

Notification Policy events generated

Refer to Audit Reporting Events for the events generated.

Notification policy errors

In addition to the general error codes, notification policy operations can return the following errors:

HTTP status Top‑level code Detail code When it happens and what the response contains

HTTP status	Top‑level code	Detail code	When it happens and what the response contains
400	`INVALID_DATA`	`EMPTY_VALUE` or `INVALID_VALUE` or `OUT_OF_RANGE`	Message: `Validation Error : [<field> <message>]` (for example, Validation Error : [name must contain only Unicode letters, marks, numbers, spaces, forward slashes, dots, apostrophes, underscores, or hyphens] , `Validation Error : [quotas[0].type invalid value]`, `Validation Error : [quotas[0].total must be greater than or equal to 1]`, `Validation Error : [cooldownConfiguration.sms.periods[0] duration must be between [10..600] seconds]`, `Validation Error : [cooldownConfiguration.sms.resendLimit must be less than or equal to 10]`, or `Validation Error : [countryLimit.countries ISO country code is not valid: <code>]`) When and details When: A `POST` Create Notification Policy or `PUT` Update Notification Policy request body fails constraint validation (for example, the request omits `name` or `quotas`, uses an invalid `quotas[].type` or `countryLimit.type`, sets `quotas[].total` below 1, sets a cooldown `periods[].duration` outside 10 seconds to 10 minutes, sets `resendLimit` outside 1 to 10, or uses an invalid ISO country code). Details: Per violated constraint: detail `EMPTY_VALUE` for `NotNull`, `NotEmpty`, or `NotBlank` constraints, `INVALID_VALUE` otherwise (including `Min` and `Max` constraints and custom validators), target = the field path, message = the constraint message. A `name` that exceeds its 256-character length limit is reported as `OUT_OF_RANGE` with `rangeMinimumValue` and `rangeMaximumValue` in `innerError`. Class-level validators are reported with target = the property path of the object that failed (for example `quotas[0]` or `cooldownConfiguration.sms`) and their own message: `Must contain either total or claimed and unclaimed` for a quota that omits `total` or provides it together with `claimed` and `unclaimed`, `Cooldown periods must be populated` for an enabled method without periods, `Must have 3 cooldown periods` for a periods array without exactly three entries, `resendLimit must be populated` for an enabled method without a resend limit. Custom field validators on nested objects are reported the same way, with the field path as the target (for example `countryLimit.countries` with `There are duplicates countries: [<codes>]` for duplicate country codes).
400	`INVALID_REQUEST`	`INVALID_PARAMETER`	Message: `The request could not be completed. The request was malformed or invalid.` When and details When: A create or update request violates a policy business rule: the quotas reference a delivery method other than `SMS`, `EMAIL`, `VOICE`, or `WHATSAPP` (`The invalid delivery methods: [<methods>]`), the same delivery method appears in more than one quota (`The delivery methods: [<methods>] appears in few quotas`), a provider fallback chain contains `PINGONE_TWILIO` as the only provider (`Fallback chain must contain at least one provider other than PINGONE_TWILIO`), `PINGONE_TWILIO` is not last in a fallback chain (`PINGONE_TWILIO must be the last provider in the fallback chain`), or the last provider condition includes countries (`The last condition must have countries set to null.`). Details: Detail `INVALID_PARAMETER` with the rule-violation message and target `policy`.
400	`INVALID_REQUEST`	`INVALID_PARAMETER`	Message: `The request could not be completed. The request was malformed or invalid.` When and details When: A create or update request sets a quota limit above the environment’s allowed maximum: a user quota above 50, an environment quota above 100 in a trial environment, or a user quota above 50 in a paid environment. Details: Detail `INVALID_PARAMETER` with the limit message — `User quota for trial environment must be maximum of 50`, `Environment quota for trial environment must be maximum of 100`, or `User quota for paid environment must be maximum of 50` — and target `quota`. A `POST` or `PUT` request with an empty `quotas` array in a trial environment returns the message `Notification quota must be provided for trial environment`.
400	`INVALID_DATA`	`UNIQUENESS_VIOLATION`	Message: `The request could not be completed. One or more validation errors were in the request.` When and details When: A create or update request uses a policy `name` that already exists in the environment (case-insensitive). Details: Detail `UNIQUENESS_VIOLATION` with message `A resource with the specified name already exists.`, target `name`, and `existingId` in `innerError` holding the ID of the existing policy.
400	`REQUEST_FAILED`	`INVALID_VALUE`	Message: `A query string parameter or value is not valid for this request.` When and details When: A create or update request sets `countryLimit.type` to `ALLOWED` or `DENIED` without including the `countryLimit.countries` property. Details: Detail `INVALID_VALUE` with message `null value` and target `countryLimit.countries`.
400	`INVALID_DATA`	`INVALID_VALUE`	Message: `The request could not be completed. One or more validation errors were in the request.` When and details When: A create or update request includes a provider ID in `providerConfiguration.conditions[].fallbackChain` that does not match a Phone Delivery Settings resource in the environment (a value other than `PINGONE_TWILIO`). Details: Detail `INVALID_VALUE` with message `PhoneDeliverySettings resource not found, id=<id>`.
400	`REQUEST_FAILED`	`CONSTRAINT_VIOLATION`	Message: `The request violates a constraint imposed by the service.` When and details When: A `PUT` Update Notification Policy request sets `default` to `false` on the environment’s current default policy, or a `DELETE` operation targets the default policy. Details: Detail `CONSTRAINT_VIOLATION` with target `policy` and the message `Attempt to remove default notifications policy for environmentId=<environmentId>` for the `DELETE` case, or `Attempt to unset notifications policy from default to non-default for environmentId=<environmentId>. There must be a default policy.` for the `PUT` case.
400	`REQUEST_FAILED`	`CONSTRAINT_VIOLATION`	Message: `The request could not be completed. There was an issue processing the request.` When and details When: A create, update, or delete request for a notification policy is submitted while a PingID-to-PingOne deployment is in process for the environment. Details: Detail `CONSTRAINT_VIOLATION` with message: The notifications policy could not be updated because a deployment of PingID to PingOne is also in process. Try again in a few minutes.
403	`ACCESS_FAILED`	`LICENSE_EXCEEDED`	Message: `The request exceeded your license limit.` When and details When: A create or update request includes `PINGONE_TWILIO` in a provider fallback chain for an environment whose license does not include the Ping SMS account capability. Details: Detail `LICENSE_EXCEEDED` with message `Fallback to Ping phone providers isn’t allowed for environment=<environmentId>`.
403	`ACCESS_FAILED`	None	Message: `The actor attempting to perform the request is not authorized.` When and details When: The actor lacks the permission for the operation: `notifications:create:notificationsPolicy` (`POST` Create Notification Policy), `notifications:read:notificationsPolicy` (`GET` operations), `notifications:update:notificationsPolicy` (`PUT` Update Notification Policy), or `notifications:delete:notificationsPolicy` (`DELETE` Delete Notification Policy). Details: None.
404	`NOT_FOUND`	None	Message: `The request could not be completed. The requested resource was not found.` When and details When: A request specifies a `policyId` that does not exist in the environment (including requests that specify an environment that does not exist, which fail the same policy lookup). Details: Detail without a code, carrying the message `Notifications policy not found: <policyId>` with target `policy`.
409	`INVALID_DATA`	`INVALID_VALUE`	Message: `The request could not be completed. One or more validation errors were in the request.` When and details When: A `DELETE` Delete Notification Policy request targets a policy that is referenced by one or more MFA device authentication policies. Details: Detail `INVALID_VALUE` with message `Cannot delete notifications policy referenced by MFA policy`, target `deviceAuthenticationPolicies`, and `referencingMFAPolicies` in `innerError` listing the names and IDs of the referencing policies.
429	`REQUEST_LIMITED`	`QUOTA_EXCEEDED`	Message: `The request will exceed your quota.` When and details When: A `POST` Create Notification Policy request exceeds the maximum number of notification policies allowed per environment (100). Details: Detail `QUOTA_EXCEEDED` with message `The max number of notification policies for this environment has been reached.`, target `policy`, and `maximumAllowed` in `innerError`.

400

INVALID_DATA

EMPTY_VALUE or INVALID_VALUE or OUT_OF_RANGE

Message: Validation Error : [<field> <message>] (for example,

Validation Error : [name must contain only Unicode letters, marks, numbers, spaces, forward slashes, dots, apostrophes, underscores, or hyphens]

, Validation Error : [quotas[0].type invalid value], Validation Error : [quotas[0].total must be greater than or equal to 1], Validation Error : [cooldownConfiguration.sms.periods[0] duration must be between [10..600] seconds], Validation Error : [cooldownConfiguration.sms.resendLimit must be less than or equal to 10], or Validation Error : [countryLimit.countries ISO country code is not valid: <code>])

When and details

When: A POST Create Notification Policy or PUT Update Notification Policy request body fails constraint validation (for example, the request omits name or quotas, uses an invalid quotas[].type or countryLimit.type, sets quotas[].total below 1, sets a cooldown periods[].duration outside 10 seconds to 10 minutes, sets resendLimit outside 1 to 10, or uses an invalid ISO country code).

Details: Per violated constraint: detail EMPTY_VALUE for NotNull, NotEmpty, or NotBlank constraints, INVALID_VALUE otherwise (including Min and Max constraints and custom validators), target = the field path, message = the constraint message. A name that exceeds its 256-character length limit is reported as OUT_OF_RANGE with rangeMinimumValue and rangeMaximumValue in innerError. Class-level validators are reported with target = the property path of the object that failed (for example quotas[0] or cooldownConfiguration.sms) and their own message: Must contain either total or claimed and unclaimed for a quota that omits total or provides it together with claimed and unclaimed, Cooldown periods must be populated for an enabled method without periods, Must have 3 cooldown periods for a periods array without exactly three entries, resendLimit must be populated for an enabled method without a resend limit. Custom field validators on nested objects are reported the same way, with the field path as the target (for example countryLimit.countries with There are duplicates countries: [<codes>] for duplicate country codes).

400

INVALID_REQUEST

INVALID_PARAMETER

Message: The request could not be completed. The request was malformed or invalid.

When and details

When: A create or update request violates a policy business rule: the quotas reference a delivery method other than SMS, EMAIL, VOICE, or WHATSAPP (The invalid delivery methods: [<methods>]), the same delivery method appears in more than one quota (The delivery methods: [<methods>] appears in few quotas), a provider fallback chain contains PINGONE_TWILIO as the only provider (Fallback chain must contain at least one provider other than PINGONE_TWILIO), PINGONE_TWILIO is not last in a fallback chain (PINGONE_TWILIO must be the last provider in the fallback chain), or the last provider condition includes countries (The last condition must have countries set to null.).

Details: Detail INVALID_PARAMETER with the rule-violation message and target policy.

400

INVALID_REQUEST

INVALID_PARAMETER

Message: The request could not be completed. The request was malformed or invalid.

When and details

When: A create or update request sets a quota limit above the environment’s allowed maximum: a user quota above 50, an environment quota above 100 in a trial environment, or a user quota above 50 in a paid environment.

Details: Detail INVALID_PARAMETER with the limit message — User quota for trial environment must be maximum of 50, Environment quota for trial environment must be maximum of 100, or User quota for paid environment must be maximum of 50 — and target quota. A POST or PUT request with an empty quotas array in a trial environment returns the message Notification quota must be provided for trial environment.

400

INVALID_DATA

UNIQUENESS_VIOLATION

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A create or update request uses a policy name that already exists in the environment (case-insensitive).

Details: Detail UNIQUENESS_VIOLATION with message A resource with the specified name already exists., target name, and existingId in innerError holding the ID of the existing policy.

400

REQUEST_FAILED

INVALID_VALUE

Message: A query string parameter or value is not valid for this request.

When and details

When: A create or update request sets countryLimit.type to ALLOWED or DENIED without including the countryLimit.countries property.

Details: Detail INVALID_VALUE with message null value and target countryLimit.countries.

400

INVALID_DATA

INVALID_VALUE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A create or update request includes a provider ID in providerConfiguration.conditions[].fallbackChain that does not match a Phone Delivery Settings resource in the environment (a value other than PINGONE_TWILIO).

Details: Detail INVALID_VALUE with message PhoneDeliverySettings resource not found, id=<id>.

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

Message: The request violates a constraint imposed by the service.

When and details

When: A PUT Update Notification Policy request sets default to false on the environment’s current default policy, or a DELETE operation targets the default policy.

Details: Detail CONSTRAINT_VIOLATION with target policy and the message Attempt to remove default notifications policy for environmentId=<environmentId> for the DELETE case, or Attempt to unset notifications policy from default to non-default for environmentId=<environmentId>. There must be a default policy. for the PUT case.

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

Message: The request could not be completed. There was an issue processing the request.

When and details

When: A create, update, or delete request for a notification policy is submitted while a PingID-to-PingOne deployment is in process for the environment.

Details: Detail CONSTRAINT_VIOLATION with message:

The notifications policy could not be updated because a deployment of PingID to PingOne is also in process. Try again in a few minutes.

403

ACCESS_FAILED

LICENSE_EXCEEDED

Message: The request exceeded your license limit.

When and details

When: A create or update request includes PINGONE_TWILIO in a provider fallback chain for an environment whose license does not include the Ping SMS account capability.

Details: Detail LICENSE_EXCEEDED with message Fallback to Ping phone providers isn’t allowed for environment=<environmentId>.

403

ACCESS_FAILED

None

Message: The actor attempting to perform the request is not authorized.

When and details

When: The actor lacks the permission for the operation: notifications:create:notificationsPolicy (POST Create Notification Policy), notifications:read:notificationsPolicy (GET operations), notifications:update:notificationsPolicy (PUT Update Notification Policy), or notifications:delete:notificationsPolicy (DELETE Delete Notification Policy).

Details: None.

404

NOT_FOUND

None

Message: The request could not be completed. The requested resource was not found.

When and details

When: A request specifies a policyId that does not exist in the environment (including requests that specify an environment that does not exist, which fail the same policy lookup).

Details: Detail without a code, carrying the message Notifications policy not found: <policyId> with target policy.

409

INVALID_DATA

INVALID_VALUE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A DELETE Delete Notification Policy request targets a policy that is referenced by one or more MFA device authentication policies.

Details: Detail INVALID_VALUE with message Cannot delete notifications policy referenced by MFA policy, target deviceAuthenticationPolicies, and referencingMFAPolicies in innerError listing the names and IDs of the referencing policies.

429

REQUEST_LIMITED

QUOTA_EXCEEDED

Message: The request will exceed your quota.

When and details

When: A POST Create Notification Policy request exceeds the maximum number of notification policies allowed per environment (100).

Details: Detail QUOTA_EXCEEDED with message The max number of notification policies for this environment has been reached., target policy, and maximumAllowed in innerError.

PingOne Platform APIs

Notification Policies

Parameters for creating/updating notification policies

Notification Policy events generated

Notification policy errors