Support & Error Reference

A fast path to diagnosis and escalation when something isn't working.

---

Error codes reference

Code	HTTP	Description	Action
MISSING_API_KEY	401	No API key provided	Add an X-API-Key header to the request.
INVALID_API_KEY	401	Key not found or revoked	Check the key in your dashboard under Settings → API Keys.
INSUFFICIENT_FUNDS	422	Source wallet balance too low	Check the balance before initiating a debit.
WALLET_NOT_FOUND	404	Wallet ID does not exist	Verify the wallet was created and the ID is correct.
WALLET_FROZEN	422	Wallet is frozen	Check the wallet's status in the dashboard, or contact support if unexpected.
WALLET_CLOSED	422	Wallet is closed	Create a new wallet — closed wallets are terminal.
INVALID_CURRENCY	400	Only NGN is supported	Use "NGN" as the currency value.
DUPLICATE_REFERENCE	409	Reference already used	Use a new, unique reference for this transaction.
SAME_WALLET_TRANSFER	400	Source and destination wallet are identical	Use two different wallet IDs.
AMOUNT_TOO_LOW	400	Amount below the minimum	The minimum is 1 kobo.
INVALID_SPLIT_CONFIG	400	Split config missing required fields	Check the split_config object against the Split Payments guide.
QR_INTENT_EXPIRED	410	QR intent past its 15-minute expiry	Create a new intent.
QR_INTENT_ALREADY_PAID	409	Intent already consumed	Check the transaction status — it likely already succeeded.
USSD_SESSION_EXPIRED	410	The 3-minute session window elapsed	Initiate a new USSD session.
KYC_ALREADY_VERIFIED	409	User is already verified	Check KYC status before resubmitting.
RATE_LIMIT_EXCEEDED	429	Too many requests	Respect the Retry-After value and back off.
INTERNAL_ERROR	500	Unexpected server error	Retry with exponential backoff. If it persists, contact support.

This table covers the error codes referenced throughout the integration guides. If you encounter a code not listed here, treat it the same as INTERNAL_ERROR — retry with backoff, and include the code verbatim when contacting support.

---

Using request IDs for support

Every PayKore API response — success or error — includes a meta.request_id field:

{
  "error": {
    "code": "INSUFFICIENT_FUNDS",
    "message": "The source wallet does not have sufficient funds for this transfer.",
    "http_status": 422
  },
  "meta": {
    "request_id": "req_6nOpQ7rStU"
  }
}

Always include this ID when contacting support. It lets the team look up the exact request in PayKore's logs — the timestamp, the payload, the internal processing trace — without you needing to describe or reconstruct what happened. A support request with a request_id is typically resolved far faster than one without.

---

Status page

Before contacting support, check status.paykore.dev for any known incidents. If there's an active incident affecting the endpoint or feature you're seeing issues with, it will be listed there along with an estimated resolution time — often faster than waiting on a support reply for something already being actively worked on.

---

Contacting support

• Email: support@paykore.dev
• Community: join the PayKore Developer Discord (link in your dashboard) for peer support and product announcements.

Response time SLA by tier:

Tier	Response time
Starter	48 hours
Growth	24 hours
Scale	4 hours

When emailing support, include: your partner ID, the relevant request_id (or several, if the issue spans multiple requests), and a brief description of what you expected versus what happened.

---

Next steps

• Authentication → — Error responses for key-related issues specifically.
• Webhooks Overview → — Debugging delivery issues via the dashboard's delivery log.