Skip to Content
SandboxOne-time paymentsJSON v3 errors (HTTP)

JSON v3 errors: HTTP codes

The error body is the same for every code: {"success": false, "error": {"code": "…", "message": "…", "next_step": "…"}}. Branch on error.code, not on the texts — they may change. The “how to reproduce” column gives a ready way to get each code in the sandbox.

error.next_step is an imperative instruction on what to do next (“take a fresh X-Timestamp”, not “invalid timestamp”): the error is read not by a human in a log but by the next iteration of your code or an AI agent. A sandbox field — the production contract does not have it, so do not rely on it in your logic.

HTTPerror.codeWhenWhat to doHow to reproduce
401AUTH_INVALID_SIGNATUREThe signature does not match, authentication headers are missing, the signature version is unsupported or the login is unknown — the exact reason is in error.messageRecompute it by the formula; common causes are signing the wrong timestamp or stray whitespace in the secretReplace X-Signature with 64 zeros; a request with no headers; X-Signature-Version: 2; a non-existent login
401AUTH_INVALID_TIMESTAMPTime drift over ±20 minutesTake a fresh UTC timestamp; check the server clock and that the time really is UTCAn X-Timestamp a day old
403AUTH_INVALID_PROJECTproject_id does not belong to the partner or is inactiveUse your own project_id; in the sandbox it is 1001/projects/999999/invoices
400BAD_REQUESTThe POST /invoices body is not a JSON objectSend a JSON object; no invoice is created in this caseA not json body
400TEST_CALLBACK_URL_FORBIDDENtest_info.callback_url without the partner flagThe callback address is configured per project; ask the sandbox administrators for the flagSend callback_url with the demo credentials
409INVOICE_ALREADY_EXISTSThe customer already has an open invoice; its id is in error.details.invoice_idRead the existing invoice or cancel it instead of creating a second orderTwo POST /invoices in a row for the same msisdn
404INVOICE_NOT_FOUNDNo invoice with this id in this projectCheck invoice_id and project_idGET /invoices/{random-uuid}
422INVALID_PAYMENT_METHODUnknown payment_methodAllowed: sbp, sberpay_desktop, sberpay_mobile, or omit the field (card)"payment_method": "paypal"
422INVOICE_NOT_PAIDRefund of an unpaid invoiceWait for payment_status: PAIDrefund right after creation
422INVOICE_NOT_AUTHORIZEDWrong PIN; the response carries the attempts leftIn the sandbox the correct PIN is 1234"pin_code": "0000"
422INVOICE_AUTH_ATTEMPTS_EXCEEDEDThree PIN attempts used up — the invoice will not accept authorization again, even with the right codeCreate a new invoiceThree wrong PINs in a row
409CONTRACT_DRAFT_EXISTSA contract with this merchant_contract_id already exists and awaits the PIN; its id is in error.details.contract_idConfirm the existing contract instead of creating a second oneTwo POST /contracts in a row with the same merchant_contract_id
409CONTRACT_ALREADY_EXISTSA contract with this merchant_contract_id is already confirmed; its id is in error.details.contract_idCharge against the existing contractPOST /contracts with the number of a confirmed contract
404CONTRACT_NOT_FOUNDThe contract is unknown or cancelledCheck contract_id and project_idPOST /contracts/{random-uuid}/authorize
409CONTRACT_ALREADY_AUTHORIZEDThe contract is already confirmedNo need to confirm it againA second authorize of the same contract
422CONTRACT_NOT_AUTHORIZEDWrong contract PINIn the sandbox the correct PIN is 1234"pin_code": "0000" in POST /contracts/{contract_id}/authorize
422CONTRACT_AUTH_ATTEMPTS_EXCEEDEDThree PIN attempts used up — the contract will not accept even the right codeThis contract can no longer be confirmedThree wrong PINs in a row

Three more codes depend on settings and infrastructure: TEST_CALLBACK_URL_REJECTED and TEST_CALLBACK_URL_RATE_LIMITED reach only partners with test_info.callback_url enabled (see “Sandbox knobs”), and SERVICE_UNAVAILABLE (503) means the sandbox could not assemble the prepared response — retry the request.

Error body
{
  "success": false,
  "error": {
    "code": "INVOICE_NOT_AUTHORIZED",
    "message": "Wrong PIN, 2 attempts left"
  }
}
Authentication errors — in the same envelope
// 401 and 403 arrive in the same {success, error}
// envelope as every other error
{
  "success": false,
  "error": { "code": "AUTH_INVALID_SIGNATURE", "message": "…" }
}
CallbacksResultCode triggers