# 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

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.kwikpaisa.com/v3-guide/error-handling/error-codes.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.