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
400 Bad Request
4990
Request signature was not included or didn’t match expected format
Client certificate not provided (mTLS)
400 Bad Request
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
4991
Signature validation failed. Ensure body and headers are signed correctly.
Unauthorized – no valid credentials
401 Unauthorized
4970
Access token is missing or invalid.
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
4001
You referenced a paymentId or transactionId that does not exist.
Duplicate payment (idempotency conflict)
409 Conflict or 200 OK
3001 / 4010
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.
Gateway failure or downstream provider error
502 Bad Gateway
8003
An upstream service failed to respond correctly. Try again later or contact support if persistent.
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​

Example 1

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

Example 2

{
  "status": "DECLINED",
  "statusInfo": {
    "reasonCode": "4990",
    "message": "Signature error"
  },
  "callId": "0af7a364bc7745f2-b823fc"
}

Example 3

{
  "status": "DECLINED",
  "statusInfo": {
    "reasonCode": "4980",
    "message": "Certificate error"
  },
  "callId": "dccdf12110264f4c-a19b2c"
}
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
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
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
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
Client transaction ID idempotency conflict
Conflicting payload for same transaction ID.
Adjust Logic
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
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
4800
Request not allowed
4801
Method not allowed
4802
Country not allowed
4803
Request too large
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
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
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
9998
Signing key error
There was an unexpected error at signing the key.
Retry
9999
Internal Server Error
Unhandled internal error.
Retry