03 - Errors & Response Codes

Standard Response Format

All API responses follow this consistent structure:

Success:

{
  "success": true,
  "correlation_id": "8000001a-0000-fd00-b63f-84710c7967bb",
  "code": "OTP_CONFIRMED",
  "message": "OTP Confirmed Successfully",
  "data": { ... }
}

Error:

{
  "success": false,
  "correlation_id": "8000001a-0000-fd00-b63f-84710c7967bb",
  "code": "INVALID_OTP",
  "message": "Detailed error description",
  "data": null
}

Security / Authentication Codes

These codes are returned by the gateway before the request reaches the business logic. Applies to all endpoints.

HTTP	Code	Description
`401`	`MISSING_HEADERS`	One or more mandatory headers (`X-Partner-Id`, `X-Api-Key`, `X-Timestamp`, `X-Nonce`, `X-Signature`) are absent.
`401`	`INVALID_TIMESTAMP`	`X-Timestamp` is outside the ±5 minute window or has an invalid format.
`401`	`UNAUTHORIZED`	Invalid `X-Partner-Id` or `X-Api-Key`.
`401`	`DUPLICATE_NONCE`	The `X-Nonce` value has already been used.
`401`	`INVALID_SIGNATURE`	The computed HMAC-SHA256 signature does not match `X-Signature`.
`429`	`RATE_LIMIT_EXCEEDED`	Too many requests per minute for this partner.

3.1 On-Demand (One-Time Charge)

3.1.1 Create Charge (OTP Flow) — `POST /on-demand/charges`

HTTP	Code	`success`	Description
`202`	`CHARGE_CREATED`	`true`	Charge successfully initiated. OTP SMS sent to user.
`400`	`INVALID_REQUEST`	`false`	Missing or invalid required fields in the request body.
`409`	`DUPLICATE_PARTNER_REF`	`false`	A charge with this `partner_ref_id` already exists for this partner.
`500`	`CHARGE_FAIL`	`false`	Unexpected internal error. Contact support.

3.1.2 Confirm OTP (Execute Charge) — `POST /on-demand/charges/{transaction_id}/otp/confirm`

HTTP	Code	`success`	Description
`200`	`OTP_CONFIRMED`	`true`	OTP validated successfully. Payment is being processed.
`400`	`INVALID_REQUEST`	`false`	Missing `otp` or `payment_method` in the request body.
`400`	`EXPIRED_TRANSID`	`false`	The transaction has expired. User must initiate a new charge.
`400`	`PIN_OVER_ERROR`	`false`	Maximum OTP attempts exceeded. User must initiate a new charge.
`400`	`INVALID_OTP`	`false`	The OTP entered by the user is incorrect.
`400`	`INVALID_MSISDN`	`false`	The mobile number is not valid or not registered with the carrier.
`400`	`INVALID_AMOUNT`	`false`	The charge amount is invalid or rejected by the payment provider.
`400`	`DUPLICATE_TRANSACTION`	`false`	This transaction has already been processed.
`400`	`INVALID_TRANSACTION`	`false`	The transaction ID is no longer recognized by the payment provider. Re-initiate.
`404`	`UNKNOWN_TRANSID`	`false`	The `transaction_id` in the URL path was not found.
`500`	`MISSING_DATA`	`false`	Internal data required to process the charge is missing. Contact support.
`500`	`GATEWAY_CONFIGURATION_ERROR`	`false`	A payment provider configuration issue occurred. Contact support.
`500`	`INTERNAL_ERROR`	`false`	Unexpected internal error. Contact support.

3.1.3 Check Transaction — `GET /on-demand/charges/check?transaction_id={id}`

HTTP	Code	`success`	Description
`200`	`CHARGE_STATUS_RETRIEVED`	`true`	Status successfully retrieved from the payment provider.
`400`	`INVALID_REQUEST`	`false`	`transaction_id` query parameter is missing.
`404`	`NOT_FOUND`	`false`	The `transaction_id` was not found or has no active token.
`500`	`INTERNAL_ERROR`	`false`	Failed to communicate with the payment provider. Retry later.

3.2 Recurring (Subscription)

3.2.1 Create Subscription — `POST /partner-dcb/v1/subscriptions`

HTTP	Code	`success`	Description
`202`	`SUBSCRIPTION_CREATED`	`true`	Subscription request accepted. OTP SMS sent to the user.
`400`	`INVALID_REQUEST`	`false`	Missing or invalid required fields in the request body.
`400`	`INVALID_MSISDN`	`false`	The provided MSISDN is not a valid XL number.
`400`	`PRODUCT_ID_NOT_FOUND`	`false`	The `product_id` is not registered or invalid.
`400`	`AMOUNT_FAILED`	`false`	The `amount` does not match the registered product price.
`409`	`DUPLICATE_REF_ID`	`false`	A subscription with this `partner_ref_id` already exists for this partner.
`500`	`GATEWAY_CONFIGURATION_ERROR`	`false`	Invalid configuration at the carrier side. Contact support.
`502`	`PAYMENT_PROVIDER_ERROR`	`false`	The carrier could not process the request. Contact support.
`503`	`SERVICE_UNAVAILABLE`	`false`	The service is temporarily unavailable. Retry later.
`500`	`INTERNAL_SERVER_ERROR`	`false`	Unexpected internal error. Contact support.

3.2.2 Confirm OTP — `POST /partner-dcb/v1/subscriptions/{requestId}/otp/confirm`

HTTP	Code	`success`	Description
`200`	`OTP_CONFIRMED`	`true`	OTP confirmed. Awaiting final activation from operator.
`400`	`INVALID_REQUEST`	`false`	Missing `otp` or `payment_method` in the request body.
`400`	`INVALID_OTP`	`false`	The OTP entered by the user is incorrect.
`400`	`INSUFFICIENT_BALANCE`	`false`	User does not have enough balance. Note: Treated as `OTP_CONFIRMED` internally — the final result will be delivered via Callback.
`404`	`NOT_FOUND`	`false`	The `requestId` in the URL path was not found.
`409`	`INVALID_STATE`	`false`	The subscription is in a state that does not allow OTP confirmation (e.g., already confirmed or expired).
`500`	`GATEWAY_CONFIGURATION_ERROR`	`false`	Invalid configuration at the carrier side. Contact support.
`502`	`PAYMENT_PROVIDER_ERROR`	`false`	An error occurred at the carrier side during OTP processing. Contact support.
`500`	`INTERNAL_SERVER_ERROR`	`false`	Unexpected internal error. Contact support.

3.2.3 Unsubscribe — `POST /partner-dcb/v1/subscriptions/unsubscribe`

HTTP	Code	`success`	Description
`200`	`UNSUBSCRIBE_ACCEPTED`	`true`	Unsubscribe request accepted.
`400`	`INVALID_REQUEST`	`false`	Missing or invalid required fields in the request body.
`400`	`INVALID_MSISDN`	`false`	The provided MSISDN is not valid.
`404`	`SUBSCRIPTION_NOT_FOUND`	`false`	No active subscription found for the given MSISDN and `product_id`.
`409`	`ALREADY_UNSUBSCRIBED`	`false`	The subscription has already been unsubscribed.
`409`	`DUPLICATE_REQUEST`	`false`	An identical unsubscribe request is already in progress.
`502`	`PAYMENT_PROVIDER_ERROR`	`false`	An error occurred at the carrier side. Contact support.
`500`	`INTERNAL_SERVER_ERROR`	`false`	Unexpected internal error. Contact support.

[!TIP]
For any 5xx error, contact Triyakom support and provide the transaction_id or partner_ref_id to facilitate log tracing.

Errors & Response Codes

03 - Errors & Response Codes#

Standard Response Format#

Security / Authentication Codes#

3.1 On-Demand (One-Time Charge)#

3.1.1 Create Charge (OTP Flow) — POST /on-demand/charges#

3.1.2 Confirm OTP (Execute Charge) — POST /on-demand/charges/{transaction_id}/otp/confirm#

3.1.3 Check Transaction — GET /on-demand/charges/check?transaction_id={id}#

3.2 Recurring (Subscription)#

3.2.1 Create Subscription — POST /partner-dcb/v1/subscriptions#

3.2.2 Confirm OTP — POST /partner-dcb/v1/subscriptions/{requestId}/otp/confirm#

3.2.3 Unsubscribe — POST /partner-dcb/v1/subscriptions/unsubscribe#

03 - Errors & Response Codes

Standard Response Format

Security / Authentication Codes

3.1 On-Demand (One-Time Charge)

3.1.1 Create Charge (OTP Flow) — `POST /on-demand/charges`

3.1.2 Confirm OTP (Execute Charge) — `POST /on-demand/charges/{transaction_id}/otp/confirm`

3.1.3 Check Transaction — `GET /on-demand/charges/check?transaction_id={id}`

3.2 Recurring (Subscription)

3.2.1 Create Subscription — `POST /partner-dcb/v1/subscriptions`

3.2.2 Confirm OTP — `POST /partner-dcb/v1/subscriptions/{requestId}/otp/confirm`

3.2.3 Unsubscribe — `POST /partner-dcb/v1/subscriptions/unsubscribe`