Errors

Types

The codes you will meet first

{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_missing",
    "message": "No such payment intent: pi_3KqL8xQpR2sT7vW9yZ1aB4cX",
    "request_id": "req_8fK2mN4pQ6rSaB3c"
  }
}

A mode mismatch reads as missing, deliberately: a test key cannot see live objects, so a live id asked for with a test key is resource_missing, not a permission error.

Handling one

import { SecureProcessingError } from "@secureprocessing/node";

try {
  await sp.paymentIntents.create(params);
} catch (err) {
  if (err instanceof SecureProcessingError) {
    if (err.type === "card_error") showCustomer(err.message);
    else if (err.isRetryable) scheduleRetry();
    else report(err.requestId);
  }
}

Quote request_id to support and we can find the exact request. Every response carries the same value in its X-Request-Id header, successes included — that is where to read it when nothing went wrong. The one exception is a replay (Idempotent-Replayed: true): the body is the original response, so its request_id is the original request’s, while the header names the replay. Quote the one in the body — it is the request that did the work.

Decline codes

The codes a refused card can carry today. Anything we cannot map returns generic_decline, and new codes may be added, so treat one you do not recognise as generic_decline.

A refused refund is 402 card_declined with decline_code: refund_failed — see refunds.

Not every attempt that fails is a decline. When the bank’s payment page expires, or the customer leaves it, before a card is tried, the payment goes back to requires_payment_method with a last_payment_error of type invalid_request_error and code payment_intent_payment_attempt_expired, and no decline_code. Nothing was charged and no card was refused. Do not tell the customer their card failed; they can simply try again.

Show the customer message rather than composing your own from the code. Some declines are deliberately vague — a card issuer will not always say why, and guessing on their behalf misleads the cardholder.

A payment the customer may be paying right now

Cancelling a payment asks the bank about it first. If the customer has already paid, the payment is settled and the cancel answers 400 — refund it instead. If they are completing 3-D Secure, or the bank’s payment page was opened less than 30 minutes ago, it answers 409 payment_in_progress and cancels nothing: the bank has no way to close a page it has handed out, so a cancel now could be followed by a payment. The message says when to try again. An unpaid payment is also cancelled automatically after a day, so you can simply leave it.

One distinction worth keeping

A 402 means the card was refused. A 503 gateway_unavailable means we could not reach the card network and no payment was taken. Telling a customer their card failed when it did not is both wrong and expensive, so we keep them apart and you should too.

Emails follow the same rule. 503 email_not_sent means we could not send it right now. Retry it. 400 email_recipient_rejected means the address was refused. Retrying will not help; send the customer the link another way. See invoicing.

And a third case that is not an error at all

Once a charge or a refund has been sent to the bank, we never answer with an error that a retry under a new key could act on — because the bank may have acted and lost only its reply, and a fresh request would charge or refund a second time. If its answer does not reach us, you usually get a success response describing where things stand: a payment intent with status: processing, a refund with status: pending, or a 202 from POST /v1/invoices/:id/pay. Each settles on its own within minutes, from the bank’s own records, and the webhook follows. Do not try again in the meantime.

When even that cannot be written, the answer is 500 outcome_unknown, and its message says which of three cases you are in:

In every case, look the payment intent or refund up rather than guessing: it settles on its own within minutes, from the bank’s own records, and its webhook follows. Retrying under a new key is the one way to pay or refund twice.

That is also why a 503 gateway_unavailable is safe to retry: it is only ever returned when nothing reached the bank.