Errors & Response Codes

How to read SADAD Pay API responses, and how to fix every error.

Every SADAD Pay API response has the same shape. This page explains how to read it, what each HTTP status code means, and how to fix each errorKey.

The response format

{
  "isValid": true,
  "errorKey": null,
  "response": {
    "invoiceId": "92968"
  }
}
{
  "isValid": false,
  "errorKey": "CustomerNameRequired",
  "response": null
}
FieldDescription
isValidtrue if the request worked, false if it did not
errorKeynull on success. On failure, a code that says what went wrong, such as CustomerNameRequired.
responseThe result on success. Usually null on failure.

🚧

Check isValid, not only the HTTP status

Most validation errors come back with HTTP 200 and "isValid": false. Always check isValid and errorKey in the body, even when the HTTP status is 200.

const body = await res.json();
if (!res.ok || !body.isValid) {
  throw new Error(`SADAD Pay error: ${res.status} ${body.errorKey}`);
}
$body = json_decode($response, true);
if ($httpCode !== 200 || empty($body['isValid'])) {
    throw new Exception('SADAD Pay error: ' . $httpCode . ' ' . ($body['errorKey'] ?? ''));
}

HTTP status codes

StatusMeaningWhat to do
200The request reached SADAD Pay. Check isValid to see if it worked.If isValid is false, fix the request using the errorKey
400The request body is not valid JSON, or a field has the wrong typeCheck the JSON and the field types. The body says which field is wrong.
401The token is missing, wrong or expiredGenerate a new Access Token. See API Keys & Authentication.
403You are not allowed to do this, for example the invoice belongs to another account or environmentCheck that you use the right keys for this environment, and the right ID
404The URL is wrongCheck the endpoint path and the base URL
500An error on the SADAD Pay sideTry again later. If it keeps happening, contact [email protected] with the request and the time.

Error keys

Authentication

errorKeyCauseHow to fix
InvalidToken (401)The Access Token has expiredGenerate a new Access Token with your refresh token
InvalidAccessToken (401)The Access Token is missing or wrongSend Authorization: Bearer {accessToken}
UnauthorizedAccess (401)The Authorization header is missing or wrongCheck the header format and the token
UnauthorizedAccess (403)The record does not exist or belongs to another account, or the feature is not enabled for youCheck the ID, the environment, and the keys you use

Invoices

POST /api/Invoice/insert, PUT /api/Invoice/update, DELETE /api/Invoice/delete. See Hosted Payment Page.

errorKeyCauseHow to fix
AmountRequiredamount is missing or 0Send an amount greater than 0
CustomerNameRequiredcustomer_Name is missingSend the customer's name
InvalidCurrencyCodecurrency_Code is missing or not supportedSend a supported currency code, such as KWD
InvoiceAmountMustEqualsToTotalItemsAmountamount is not the total of the itemsSend amount = sum of quantity × amount
InvoiceCannotBeUpdatedThe invoice is already paidCreate a new invoice instead
InvoiceCannotBeDeletedThe invoice is already paidRefund it instead. See Refunds.

Embedded Payment

POST /api/EmbeddedPayment/allow_domain and intiate_order_session. See Embedded Payment.

errorKeyCauseHow to fix
InvalidDomainNameThe domain is not validSend the domain only, without https:// or a path
DomainAlreadyExistThe domain is already registeredNothing to do
PaymentMethodRequiredpaymentGatewayCode is missingSend Knet, CCCSSA or ApplePay
ReferenceNumberRequiredref_Number is missingSend your order number
AmountRequired, CustomerNameRequired, InvalidCurrencyCode, InvoiceAmountMustEqualsToTotalItemsAmountAs for invoicesAs for invoices

Payment links and product links

See Invoicing & Payment Links and Product Links.

errorKeyEndpointCauseHow to fix
InvalidKeycreatepaymentlinkinvoiceThe payment link key does not existCheck paymentLink_Key
CustomerMobileRequiredcreatepaymentlinkinvoiceReturned when the key is wrong and no mobile number is sentCheck paymentLink_Key first
InvalidAmountcreatepaymentlinkinvoiceThe amount does not match a fixed link, or is outside a variable link's rangeSend an amount the link allows
NameEnRequired / NameArRequiredProduct/insertThe English or Arabic name is missingSend both name_En and name_Ar
PriceRequiredProduct/insertprice is missing or 0Send a price greater than 0
CustomerMobileRequiredcreateproductlinkinvoicecustomer_Mobile is missingSend the customer's mobile number
InvalidProductAmountcreateproductlinkinvoiceAn item's amount is not the product's priceSend each product's current price
YouExceededAvailableQuantitycreateproductlinkinvoiceThe quantity is more than the stock leftLower the quantity, or add stock
InvoiceAmountMustEqualsToTotalItemsAmountcreateproductlinkinvoicetotalAmount is not the sum of the itemsSend the correct total

Installments and subscriptions

See Installments and Subscriptions.

errorKeyEndpointCauseHow to fix
VendorIdRequiredInstallmentPlan/insertvendor_Id is missingSend your vendor ID
TotalAmountRequiredInstallmentPlan/inserttotal_Amount is missing or 0Send the total
InstallmentScheduleRequiredInstallmentPlan/insertschedules is missingSend the full schedule
InvalidInstallmentScheduleNumberInstallmentPlan/insertThe number of Schedule items is not installment_CountSend one item per payment
CustomerEmailRequiredcreateinstallmentplanlinkinvoicecustomer_Email is missingSend the customer's email
AmountCannotBeGreaterThanDueAmountcreateinstallmentplanlinkinvoicetotalAmount is more than the amount duePay no more than the amount due
InvalidKeycreateSubscriptioninvoiceThe key is a subscription link key, not a customer subscription keyUse the key from /subscription/payment/{key}

Refunds

See Refunds.

errorKeyCauseHow to fix
InvalidRefundAmountThe amount is 0, or more than what is left to refundRefund no more than amount - refunded_Amount
null, with "refund_Id": 0 and "isValid": falseThe invoice is not paid, or refund_Type is not validRefund only paid invoices, with DeductFromBalance or PayAmount

Multi-supplier

See Multi-Supplier Payments.

errorKeyCauseHow to fix
SuppliersItemsRequiredAn item has no supplierIdSend a supplierId with every item
SupplierNotExistForThisVendorA supplierId is not one of your Approved suppliersCheck the ID in Suppliers
UnauthorizedAccess (403)Supplier refunds are not enabled for your accountEmail [email protected]

Getting help

If you cannot fix an error, email [email protected] with:

  • The endpoint and the environment (Sandbox or Live)
  • The request body, without your keys or tokens
  • The full response, including the HTTP status
  • The date and time of the request