> ## Documentation Index
> Fetch the complete documentation index at: https://docs.laikipay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Handling errors, response schemas, and HTTP status codes

# Errors & Status Codes

LaikiPayuses standard HTTP status codes combined with a structured JSON error envelope to describe error conditions.

***

## Standard Error Response Format

Every error response returned by the API adheres to the following JSON schema:

```json theme={null}
{
  "status": "error",
  "statusCode": 400,
  "message": "Minimum initial card funding amount is $1.00 USD",
  "error": "Bad Request",
  "timestamp": "2026-10-12T07:15:00.000Z",
  "path": "/api/v1/merchant/cards"
}
```

### Parameter Validation Errors

When a request payload fails schema validation, `message` will be an array of specific constraint violation strings:

```json theme={null}
{
  "status": "error",
  "statusCode": 400,
  "message": [
    "nameOnCard should not be empty",
    "amount must not be less than 1"
  ],
  "error": "Bad Request",
  "timestamp": "2026-10-12T07:15:00.000Z",
  "path": "/api/v1/merchant/cards"
}
```

***

## HTTP Status Code Reference

| Status Code | Reason | Description |
| :- | :- | :- |
| `200 OK` / `201 Created` | Success | The request succeeded and returned the requested data. |
| `400 Bad Request` | Client Error | Missing parameters, malformed payload, or business constraint failure (e.g., insufficient vault funds). |
| `401 Unauthorized` | Invalid Auth | Secret key missing, incorrect, expired, or mismatched with `X-Merchant-Id`. |
| `403 Forbidden` | Access Denied | Client IP address is not whitelisted, or Live operations were attempted without KYB Tier 2+. |
| `404 Not Found` | Resource Missing | The specified card ID, customer, or transaction does not exist. |
| `409 Conflict` | State Conflict | Duplicate idempotency reference or transaction already settled. |
| `429 Too Many Requests` | Rate Limited | Exceeded API rate limits. Retry with exponential backoff. |
| `500 Server Error` | Internal Error | An error occurred within Laiki Pay's platform or an upstream card processor. |

***

## Common Error Scenarios & Responses

### 1. Insufficient Vault Balance (`400 Bad Request`)

Occurs when issuing a card or funding a card with an amount greater than your available vault balance:

```json theme={null}
{
  "status": "error",
  "statusCode": 400,
  "message": "Insufficient balance in Sandbox USD vault. Required: $12.00 (Funding: $10.00, Issuance Fee: $2.00), Available: $5.00",
  "error": "Bad Request",
  "timestamp": "2026-10-12T07:15:00.000Z",
  "path": "/api/v1/merchant/cards"
}
```

### 2. Missing or Expired Bearer Token (`401 Unauthorized`)

Occurs when an API endpoint is called without an `Authorization: Bearer <accessToken>` header, or after the 15-minute token expires:

```json theme={null}
{
  "status": "error",
  "statusCode": 401,
  "message": "Missing authentication credential. Provide Authorization Bearer token.",
  "error": "Unauthorized",
  "timestamp": "2026-10-12T07:15:00.000Z",
  "path": "/api/v1/merchant/cards"
}
```

### 3. Invalid Credentials During Token Exchange (`401 Unauthorized`)

Occurs when exchanging credentials at `POST /v1/merchant/auth/token` with an incorrect Secret Key or mismatched Merchant ID:

```json theme={null}
{
  "status": "error",
  "statusCode": 401,
  "message": "Invalid credentials. Pls check try again or contact support",
  "error": "Unauthorized",
  "timestamp": "2026-10-12T07:15:00.000Z",
  "path": "/v1/merchant/auth/token"
}
```

### 4. IP Address Not Whitelisted (`403 Forbidden`)

Occurs when the calling server IP address is not included in the merchant's IP Whitelist for that environment:

```json theme={null}
{
  "status": "error",
  "statusCode": 403,
  "message": "IP address not allowed for this merchant account",
  "error": "Forbidden",
  "timestamp": "2026-10-12T07:15:00.000Z",
  "path": "/api/v1/merchant/cards"
}
```

### 5. Card Not Found (`404 Not Found`)

Occurs when requesting a card ID that does not exist or belongs to another merchant:

```json theme={null}
{
  "status": "error",
  "statusCode": 404,
  "message": "Virtual card not found",
  "error": "Not Found",
  "timestamp": "2026-10-12T07:15:00.000Z",
  "path": "/api/v1/merchant/cards/crd_invalid_id"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.