Skip to main content

Error Handling

Nopan uses structured error responses to help developers understand and react to problems quickly and effectively. All API errors follow a predictable pattern, combining standard HTTP status codes with detailed Nopan-specific reason codes.

This guide covers how errors are reported, how to troubleshoot them, and how to interpret our internal codes.

Error Code Families​

Nopan reasonCode values are grouped to make troubleshooting easier.
Use these families to decide what to fix (request vs. logic) and whether to retry.

Group
Group Type
Description
1xxx
Payment & Risk
Failures due to account balance, fraud/risk checks, or exceeded velocity thresholds.
2xxx
Customer & Session
Outcomes caused by user actions (cancel, abandon) or expired sessions.
3xxx
Idempotency & Rate Limits
Signals to prevent duplicate processing and enforce throughput limits.
4xxx
Request Validation & Authentication
Errors in payload validation, identifiers, tokens, certificates, or request signing.
5xxx
Business Rules
Operation rejected due to lifecycle or rule constraints (e.g. refunds not allowed).
6xxx
Webhooks & Security
Webhook delivery issues or requests blocked by security policies.
8xxx
Provider & Downstream
Timeouts, unsupported operations, or errors returned by external payment providers.
9xxx
Internal
Unexpected internal system failures within Nopan.

HTTP Status Codes​

We follow standard HTTP response codes to indicate success or failure.

Success​

Requests that are processed correctly (irrespective of a transaction status) return status codes in the 2xx range.

Failure​

Client-side errors return a 4xx code. These usually require action from your application.

Server-side issues return a 5xx code and indicate a problem within Nopan or downstream services.

Common Error Scenarios​

Below are examples of real-world error situations, mapped to HTTP status codes and Nopan reason codes, with tips on how to handle them.

Cause
HTTP Status
Nopan Error
What it Means / How to Fix
Missing or invalid field (e.g., amount, currency)
400 Bad Request
4000
The payload was incomplete or didn’t pass schema validation. Check required fields and formats.
Missing or malformed signature header
401 Unauthorized
4990
Request signature was not included or didn’t match expected format
Client certificate not provided (mTLS)
401 Unauthorized
4980
Your system must present a valid TLS certificate when connecting.
Token is expired or invalid
401 Unauthorized
4061
The provided token was revoked or expired. Refresh or re-authenticate.
Invalid request signature
401 Unauthorized
4992
Signature validation failed. Ensure body and headers are signed correctly.
Unauthorized – no valid credentials
401 Unauthorized
4970
Access token is missing or invalid.
Strong customer authentication (SCA) required
401 Unauthorized
4972
The payer must complete a strong customer authentication step-up (e.g. a Bizum OTP challenge) before the payment can proceed. This concerns the end customer, not your API credentials — prompt the payer to authenticate, then continue the flow.
Authenticated, but access is forbidden
403 Forbidden
4971
You’re authenticated but not authorized to access this resource (e.g., wrong scope or cert trust failure).
Payment not found
404 Not Found
5000
You referenced a paymentId or transactionId that does not exist.
Duplicate payment (idempotency conflict)
409 Conflict or 200 OK
3001 / 3002
Same `clientTransactionId` already used. Either retrying the same request (200) or a conflict in payload (409).
Rate limit exceeded
429 Too Many Requests
3000
Too many requests in a short time. Wait and retry after the cooldown period.
Payment lifecycle rule violated (e.g. capture already processed)
422 Unprocessable Content
5002
The operation is not allowed given the current state of the payment. Check the payment status before retrying.
Payment is currently being processed
423 Locked
5003
The payment is locked while a concurrent operation is in progress. Wait and retry.
Operation not supported by the consumer bank
422 Unprocessable Content
1100
The requested operation is not available for the consumer's bank.
Operation not supported by the provider
501 Not Implemented
8003
The requested operation is not available for this provider or payment method.
Gateway failure or downstream provider error
502 Bad Gateway
8004
An upstream service failed to respond correctly. Try again later or contact support if persistent.
Downstream provider did not respond in time
504 Gateway Timeout
8001
The provider timed out. Retry after a short delay; if persistent, contact Nopan support with the `callId`.
Unexpected server error
500 Internal Server Error
9999
An unknown error occurred. Retry or contact Nopan support with the `callId` included in the error response.
info

Example Responses​

{
  "status": "DECLINED",
  "statusInfo": {
    "reasonCode": "4000",
    "message": "Invalid input"
  },
  "fields": {
    "processingAccountId": "Processing Account ID is required",
    "paymentDetails.amount": "Amount is required"
  },
  "callId": "678c62b0177e4bc3-a12309"
}
Debugging with callId

Error response includes a unique callId — a trace identifier generated by Nopan.

Include it when contacting support to help us locate logs and diagnose the issue quickly.

These responses are returned immediately as part of the HTTP call and indicate problems that must be resolved before retrying or proceeding.

Nopan reason codes​

Each error response from Nopan includes a reasonCode and message. These codes are specific to Nopan and help developers understand exactly what went wrong.

Below is the full catalog of error codes returned by Nopan, including reason code returned for non-2xx response described above:

Code
Message
Description
Recommended Action
-1
Request processed successfully
Internal indicator that the flow was successful.
None
1000
Non sufficient funds
The payer account does not have enough balance.
Retry
1010
Declined by issuer
The payer's bank declined the payment.
Adjust Logic
1020
Declined. Possible fraud
Rejected based on internal or PSP risk checks.
Adjust Logic
1022
Suspicious velocity pattern
Transaction volume exceeded safe thresholds.
Adjust Logic
1100
Operation not supported by consumer bank
Operation not supported by consumer bank.
Adjust Logic
1101
Recurring payments not supported by consumer bank
The payer's bank does not support recurring payments.
Adjust Logic
2000
Session expired
Shopper took too long to complete the action.
Retry
2002
Invalid payer identifier
payerId or token is missing or malformed.
Fix Request
2003
Payments not supported for provider/currency on this account
The provider or currency combination is not enabled for this account.
Adjust Logic
3000
Rate limit exceeded
Too many requests in a short time frame.
Retry
3001
Duplicated client transaction ID
This transaction ID has already been processed.
Adjust Logic
3002
Idempotency conflict
Conflicting payload for same transaction ID.
Adjust Logic
3003
Duplicated processing account ID
The processingAccountId is already used by another processing account.
Fix Request
4000
Invalid input
The payload was incomplete or didn't pass schema validation. One or more input fields are malformed or invalid.
Fix Request
4002
Unsupported currency
The specified currency is not supported.
Fix Request
4003
Processing account not found
The processing account ID does not exist or is not active.
Fix Request
4004
Report not found
The requested report does not exist or is not accessible.
Fix Request
4005
Contractual entity not found
The contractual entity does not exist, or it does not belong to your organization.
Fix Request
4006
Merchant details are required for this account
Merchant details are required for this account. A PAYFAC account needs the legal entity name, address, city, country and MCC.
Fix Request
4007
Disputes contact name and email are required for this account
A Wero account needs the disputes contact name and email.
Fix Request
4008
Bank account is missing or invalid for its type
The bank account is missing, or its number is not valid for its type (for example, a wrong IBAN checksum).
Fix Request
4009
A request must contain between 1 and 50 accounts
A request must contain between 1 and 50 processing accounts.
Fix Request
4010
Processing account ID is repeated in the request
The same processingAccountId appears more than once in the request.
Fix Request
4011
More than one processing account with the same payment provider requested for the same contractual entity
The request contains more than one Wero account for the same contractual entity. A MERCHANT organization can only have one.
Fix Request
4012
Organization not found
The organization of your access token does not exist.
Contact Support
4060
Invalid token
The provided token is malformed or does not exist.
Fix Request
4061
Token is expired
The provided token was revoked or expired. Refresh or re-authenticate.
Fix Request
4062
Token already charged for the current subscription period
4800
Request not allowed
The request is not permitted for this resource or context.
Adjust Logic
4801
Method not allowed
The HTTP method used is not allowed for this endpoint.
Fix Request
4802
Country not allowed
Payments are not allowed from the payer's country.
Adjust Logic
4803
Request too large
The request payload exceeds the maximum allowed size.
Fix Request
4970
Authentication error
Access token is missing or invalid.
Fix Request
4971
Authorization error: Resource is not allowed
You're authenticated but not authorized to access this resource (e.g., wrong scope or cert trust failure).
Adjust Logic
4972
Strong customer authentication required
Strong customer authentication is required to complete this request.
Authenticate
4980
Certificate error
Error validating client certificate. Your system must present a valid TLS certificate when connecting.
Fix Request
4981
Certificate not trusted
Client certificate is not from a trusted authority.
Fix Request
4990
Signature error
Request signature was not included or didn't match expected format.
Fix Request
4991
Missing signature headers
Signature validation failed. Ensure body and headers are signed correctly.
Fix Request
4992
Error validating the signature
Signature validation failed. The signature check of the content has failed.
Fix Request
5000
Payment not found
Payment not found
Adjust Logic
5001
Payment already exists
Payment already exists
Adjust Logic
5002
Payment transition not allowed
Payment transition not allowed
Adjust Logic
5003
Payment is processing
Payment is currently processing
Retry
5004
Payment authorization revoked
Payment authorization has been revoked
Adjust Logic
5005
Payment has been canceled
Payment has been canceled
Adjust Logic
5006
Cancel already processed
Payment cancellation already processed
Adjust Logic
5007
Cancel is not allowed
Payment cancellation is not allowed
Adjust Logic
5008
Refund window expired
Payment refund window has expired
Adjust Logic
5009
Refund already processed
Payment refund already processed
Adjust Logic
5010
Refund not allowed
Payment refund is not allowed
Adjust Logic
5011
Refund is pending
Payment refund is pending
Retry
5012
Refund amount is not allowed
Payment refund amount is not allowed
Adjust Logic
5013
Capture window expired
Payment capture window has expired
Adjust Logic
5014
Capture already processed
Payment capture already processed
Adjust Logic
5015
Capture not allowed
Payment capture is not allowed
Adjust Logic
5016
Capture amount is not allowed
Payment capture amount is not allowed
Adjust Logic
5017
Partial refund amount is not allowed
The partial refund amount is not allowed for this payment.
Adjust Logic
5018
Partial capture amount is not allowed
The partial capture amount is not allowed for this payment.
Adjust Logic
5100
Contractual entity is not enabled
The contractual entity is not enabled yet, so it cannot have new processing accounts.
Contact Support
5101
A processing account with this payment provider already exists for this contractual entity
The contractual entity already has a Wero account. A MERCHANT organization can only have one.
Adjust Logic
6000
Webhook delivery failed
The merchant endpoint returned an error.
Fix Request
6001
Webhook not configured
No webhook endpoint defined for this event type.
Adjust Logic
8001
Provider timeout
No response received from downstream provider.
Retry
8002
Malformed provider response
Invalid or unexpected payload from provider.
Contact Support
8003
Operation not supported
Requested action not available for this provider.
Adjust Logic
8004
Provider error
An upstream service failed to respond correctly. Try again later.
Retry
9995
Upstream service error
An upstream service failed or could not be reached. Try again later.
Retry
9996
Upstream service timeout
An upstream service did not answer in time. Try again later.
Retry
9997
Service unavailable error
The service is temporarily unavailable. Try again later.
Retry
9998
Signing key error
There was an unexpected error at signing the key.
Retry
9999
Internal Server Error
Unhandled internal error.
Retry