Statuses and errors

StatusName — processing result

Value	Description
`REQUEST_ACCEPTED`	Request accepted and processed
`SECURITY_ERROR`	Signature error or `Now` drift greater than 20 minutes
`WRONG_PARAMS`	Invalid parameter set
`SERVICE_UNAVAILABLE`	A request rate limit was hit
`INTERNAL_ERROR`	Internal platform error

On error, the response additionally contains ErrorDescription (an explanation) and ErrorReasonName (a machine code).

HTTP statuses

Status	When
`400`	The body does not parse as XML or is empty
`503`	A rate limit was hit. The body carries `StatusName=SERVICE_UNAVAILABLE`
`200`	Everything else, including signature and parameter errors — check `StatusName`

ErrorReasonName codes

Code	When
`InvalidSubscriberMsisdn`	The number is not in `7XXXXXXXXXX` format
`SubscriberMustBeSpecified`	Neither a number, nor `ClientIP`, nor `CustomerType=Card` was sent
`SubscriptionAlreadyCreated`	The subscriber already has a live subscription in this project. The existing `SubscriptionID` is printed in `ErrorDescription`
`SubscriberNotSupported`	The subscriber’s operator has no billing rules
`SubscriberInBlacklist`	The number is blacklisted
`ClientIPMSISDNCountryNotEqual`	Countries by number and by IP do not match
`InvalidClientIP`	`ClientIP` does not parse as an IP address
`InvalidPinCode`	Wrong PIN; the description carries the attempts left
`ExceededSubscriptionApprovingAttempts`	Three wrong PINs in a row, or the 3-hour confirmation window expired
`SubscriptionAlreadyApproved`	The subscription is already confirmed

Rate limits

Counter	Thresholds	Methods
`ClientIP`	50 per 10 min, 200 per 60 min	all
`Subscriber_MSISDN`	6 per 2 min, 10 per 20 min	`CreateSubscription`, `CancelSubscription`
`SubscriptionProjectID`	1000 per 1 min, 3000 per 5 min	all

The counters are independent: hitting the limit for one number does not block the other subscribers of the project. Exceeding a limit gives 503.

Error response


<?xml version="1.0" encoding="utf-8"?>
<Response>
  <StatusName>SECURITY_ERROR</StatusName>
  <ErrorDescription>Signature validation failed</ErrorDescription>
  <ErrorReasonName>InvalidSignature</ErrorReasonName>
</Response>

CreateSubscription response fields

Field	Description
`SubscriptionID`	Subscription identifier in the platform — store it
`SubscriberAcceptanceRequired`	Whether subscriber confirmation is required
`SubscriberAcceptanceChannel`	Confirmation channel: `SMS_PIN` or `AUTH_PAGE`
`AuthorizeUrl`	Payment or confirmation page — for the `AUTH_PAGE` channel only
`SubscriptionStatus`	Subscription state right after creation — `Pending`
`TrialExists`	Whether the subscription has a trial period
`OperatorID`	Subscriber’s operator
`PaidUntil`	Paid until — date and time with a timezone

Notification fields

Field	Description
`EventType`	Event type, e.g. `APPROVED`
`SubscriptionStatus`	Subscription state, e.g. `Active`
`BillingIteration` / `BillingAttempt`	Billing iteration number and the attempt number within it
`CustomerPrice`	Charge amount: `currency` and `amount` attributes
`BillingOperationID`	Billing operation identifier
`BillingErrorCode`	Billing error code, `0` — success
`PaidUntil`	New end date of the paid period