Error handling

Why a request is refused, why an accepted payment still fails, and how to tell the two apart — HTTP statuses, error codes, and what to retry.

Two kinds of failure

A payment can fail in two completely different places, and they reach you through two different channels. Getting this distinction right is most of what error handling on our API is about:

Rejected at creation

Every refusal is an HTTP error whose body is a single detail string. There is no error-code field on this surface — branch on the HTTP status, and log detail for your support team.

{
  "detail": "Payment already exists"
}

401 — signing and access

All four causes below use status 401; only detail tells them apart, so log it.

422 — the request body is malformed

Schema validation failed before any business logic ran. This is the one error surface that is fully machine-readable: detail is a list, one entry per offending field.

{
  "detail": [
    {
      "type": "greater_than_equal",
      "loc": ["body", "payment", "amount"],
      "msg": "Input should be greater than or equal to 0"
    }
  ]
}

Common causes:

• currency is not a supported ISO 4217 code.
• amount is negative, or is a string / decimal instead of an integer in minor units.
• payment_id is empty or longer than 255 characters; cascade_id is longer than 40.
• A payout destination field breaks its format — phone number, account number (6–34 chars), username (3–64 chars), card expiry month/year.
• A required object (payment, card, customer) is missing entirely.

400, 404 and 409 — business rules

5xx — a fault on our side

A 500 or 502 is ours to fix, not a signal about your request. Retry with backoff, keeping the same payment_id. Two exceptions worth recognising:

• Something wrong with gate configuration… — the gate is misconfigured. Retrying will not help; contact your account manager.
• Repeated 5xx on one currency only — the currency may not be enabled on the platform. Also permanent until we act.

Failed after creation

Once you have a payment_uid, everything else arrives asynchronously. Read the outcome from the payment's status, and the reason from processing_info:

{
  "uid": "0f2c7d1e-…",
  "merchant_payment_id": "order-10231",
  "currency": "KRW",
  "amount": 50000,
  "status": "error",
  "processing_info": {
    "error_code": "amount_incorrect",
    "error_message": "Payment amount exceeds limit",
    "created_at": "2026-09-01T10:15:04Z",
    "finish_at": "2026-09-01T10:15:05Z"
  }
}

• status — decline means the payment was refused (by the payer, the provider, or your balance); error means it failed on the way. Both are terminal; neither moves money.
• processing_info.error_code — a fixed enum. This is the field to branch on.
• processing_info.error_message — a human-readable sentence. It is not derived from the code and its wording varies by route. Display it, log it, never parse it.

Error code reference

Codes are grouped by who has to act. "Retry" means: create a new payment with a new payment_id.

Your request or your configuration

The provider or the network

The payer or their instrument

Getting more detail

Add ?provide_status_history=true to the status call to receive the full transition chain. Its reason field distinguishes failures that never reached a provider from failures the provider reported:

"history": [
  {"previous_status": null,         "new_status": "initiated",  "reason": "payment_created",     "trigger": "api"},
  {"previous_status": "initiated",  "new_status": "processing", "reason": "processing_started",  "trigger": "worker"},
  {"previous_status": "processing", "new_status": "error",      "reason": "channel_update",      "trigger": "worker"}
]

failed_internal means we never got as far as the provider — a routing, limit or balance problem. channel_update means the provider answered and the answer was a failure. That single distinction resolves most "whose fault was it?" questions before you open a ticket.

Hosted gates: a failed payment is not a failed invoice

On a hosted gate, an invoice may hold several payment attempts. When an attempt fails with a transient code — network_error, channel_timeout, channel_unavailable, timeout_3ds, sms_delivery_problem, insufficient_funds, channel_decline — and the gate's attempt budget is not yet spent, the invoice returns to unpaid / paying so the payer can try again. Any other code fails the invoice immediately.

Poll /api/invoice/status with provide_payments_history=true to see every attempt and why each one failed.

Idempotency & retries

Your payment_id is the idempotency key. It must be unique within your project, and reuse is rejected with 400 Payment already exists. That makes the duplicate error your safety net rather than a problem:

1. A creation call times out or fails at the transport layer You cannot know whether we stored the payment. Do not generate a new payment_id.
2. Retry the same request with the same payment_id Fresh timestamp, fresh nonce, fresh signature — the body, including payment_id, unchanged.
3. A 200 means it went through now; a 400 Payment already exists means it went through the first time Both are success. In the second case, look the payment up by your own identifier.

resp = signed_post("/api/payment/payin/card", payload)

if resp.status_code == 400 and "already exists" in resp.json()["detail"]:
    # We already have this payment — fetch it instead of creating another.
    resp = signed_post("/api/payment/status", {"merchant_payment_id": payload["payment"]["payment_id"]})
    payment = resp.json()

Handling errors end to end

PERMANENT = {"invalid_request", "suspected_fraud", "invalid_card_bin",
             "channel_invalid_request", "channel_unknown",
             "limit_error_deposit_streak_card", "limit_error_completed_deposit_card"}

resp = signed_post("/api/payment/payin/card", payload)

if resp.status_code == 200:
    payment_uid = resp.json()["payment_id"]        # our uid; store it next to your order
elif resp.status_code == 401:
    raise ConfigError(resp.json()["detail"])       # signing / clock / key — never retry blindly
elif resp.status_code == 422:
    raise BadRequest(resp.json()["detail"])        # fix the field named in detail[].loc
elif resp.status_code == 400 and "already exists" in resp.json()["detail"]:
    payment_uid = lookup_existing(payload)         # see above — this is a success path
elif resp.status_code == 400 or resp.status_code == 404:
    raise BadRequest(resp.json()["detail"])        # currency / cascade / gate — permanent
else:                                              # 5xx
    schedule_retry(payload)                        # same payment_id, backoff

@app.post("/hooks/magicpayments")
async def on_payment(request: Request):
    verify_signature(request)                      # see Getting started
    payment = await request.json()

    match payment["status"]:
        case "success":
            credit_order(payment["merchant_payment_id"],
                         payment["processing_info"]["amount_credited"])
        case "decline" | "error":
            info = payment["processing_info"]
            fail_order(payment["merchant_payment_id"],
                       code=info["error_code"],
                       display=info["error_message"],
                       retryable=info["error_code"] not in PERMANENT)
        case _:
            pass                                   # initiated / processing — nothing to do yet

    return {"ok": True}                            # anything but 200 makes us retry

Testing & go-live

• Force each creation error once on stage: drop a header (401), send a negative amount (422), reuse a payment_id (400), send an unsupported currency (400). Confirm your code takes the right branch on each.
• Move your server's clock forward six minutes and confirm you handle Timestamp outside allowed window rather than looping.
• Ask your account manager for a test route that declines, so you exercise the decline / error callback path — not just the happy one.
• Verify your callback handler answers 200 only after it has durably recorded the update. Any other response is retried, and a handler that crashes after committing but before answering will see the same update again.
• Make your callback handler idempotent: the same terminal status can arrive more than once, and a post-settlement correction sends a fresh callback even when status did not change.
• Log payment_uid, merchant_payment_id, the HTTP status and either detail or error_code on every failure. Those are the fields our support team needs to trace a payment.