Error codes

KwikPaisa APIs use standard HTTP status codes along with structured API responses to indicate request status, authentication issues, validation failures, transaction errors, and system-level failures.

Merchants should always validate:

• HTTP status codes
• API response codes
• Response messages
• Transaction status values

Proper error handling helps build stable, secure, and reliable integrations.

---

Standard Error Response Format

{
  "status": false,
  "code": 401,
  "message": "Invalid signature."
}

HTTP Status Codes

HTTP Code	Meaning
200	Request processed successfully
201	Request created successfully
400	Bad request or invalid payload
401	Authentication failed
403	Access denied
404	Resource or transaction not found
409	Duplicate request conflict
422	Validation or business logic failure
429	Too many requests
500	Internal server error
503	Service temporarily unavailable

Authentication Errors

401 Unauthorized

Occurs when API authentication fails.

Possible Reasons

• Invalid API key
• Incorrect signature
• Expired timestamp
• Missing authentication headers

Example Response

{
  "status": false,
  "code": 401,
  "message": "Invalid signature."
}

Invalid Wallet ID

403 Forbidden

Occurs when wallet credentials do not belong to the selected environment.

Possible Reasons

• Sandbox wallet used in production
• Production wallet used in Sandbox
• Invalid merchant wallet

Example Response

{
  "status": false,
  "code": 403,
  "message": "Invalid wallet ID for selected environment."
}

---

Transaction Not Found

404 Not Found

Occurs when the requested transaction or order does not exist.

Possible Reasons

• Invalid order ID
• Invalid payout order ID
• Transaction does not exist
• Incorrect merchant credentials

Example Response

{
  "status": false,
  "code": 404,
  "message": "Payout transaction not found."
}

---

Validation Errors

400 Bad Request

Occurs when request payload validation fails.

Possible Reasons

• Missing required parameters
• Invalid JSON payload
• Incorrect request structure
• Invalid data format

Example Response

{
  "status": false,
  "code": 400,
  "message": "Invalid request payload."
}

---

Insufficient Wallet Balance

422 Unprocessable Entity

Occurs when payout wallet balance is insufficient.

Possible Reasons

• Wallet balance too low
• Transfer amount exceeds available funds

Example Response

{
  "status": false,
  "code": 422,
  "message": "Insufficient wallet balance."
}

---

Duplicate Transaction Errors

409 Conflict

Occurs when duplicate transaction references are used.

Possible Reasons

• Duplicate order_id
• Duplicate payout_order_id
• Repeated payout initiation

Example Response

{
  "status": false,
  "code": 409,
  "message": "Duplicate transaction request."
}

---

Rate Limit Errors

429 Too Many Requests

Occurs when API request limits are exceeded.

Possible Reasons

• Excessive API traffic
• Aggressive retry loops
• Burst request patterns

Example Response

{
  "status": false,
  "code": 429,
  "message": "Too many requests."
}

---

Internal Server Errors

500 Internal Server Error

Occurs when an unexpected server-side failure happens.

Possible Reasons

• Temporary infrastructure issue
• Banking partner downtime
• Internal processing error

Example Response

{
  "status": false,
  "code": 500,
  "message": "Internal server error."
}

---

Service Unavailable

503 Service Unavailable

Occurs during temporary maintenance or service interruptions.

Possible Reasons

• Scheduled maintenance
• Banking partner downtime
• Temporary service outage

Example Response

{
  "status": false,
  "code": 503,
  "message": "Service temporarily unavailable."
}

---

Recommended Error Handling Workflow

1. Validate HTTP status code
2. Read API response message
3. Log request and response
4. Retry processing carefully if applicable
5. Verify transaction status using APIs
6. Avoid duplicate transaction creation

Retry Recommendations

Retry only for temporary errors such as:

Error	Retry Recommended
429	Yes
500	Yes
503	Yes
PROCESSING status	Yes
401	No
403	No
404	Limited
422	No

Logging Recommendations

Merchants should log:

• Request payloads
• API responses
• Signature generation logs
• Webhook payloads
• Retry attempts
• Transaction references

This helps simplify:

• Debugging
• Reconciliation
• Compliance audits
• Issue tracking

---

Security Recommendations

• Never expose secret keys
• Always use HTTPS
• Validate webhook signatures
• Generate fresh timestamps
• Regenerate signatures for every retry

---

Best Practices

• Handle all API errors gracefully
• Avoid aggressive retry loops
• Use idempotent transaction IDs
• Verify transaction status server-side
• Maintain detailed transaction logs