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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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"
}

Getting Started

Virtual Cards API

Webhooks

Errors

Errors & Status Codes

Standard Error Response Format

Parameter Validation Errors

HTTP Status Code Reference

Common Error Scenarios & Responses

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

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

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

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

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

​Errors & Status Codes

​Standard Error Response Format

​Parameter Validation Errors

​HTTP Status Code Reference

​Common Error Scenarios & Responses

​1. Insufficient Vault Balance (400 Bad Request)

​2. Missing or Expired Bearer Token (401 Unauthorized)

​3. Invalid Credentials During Token Exchange (401 Unauthorized)

​4. IP Address Not Whitelisted (403 Forbidden)

​5. Card Not Found (404 Not Found)

Errors & Status Codes

Standard Error Response Format

Parameter Validation Errors

HTTP Status Code Reference

Common Error Scenarios & Responses

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

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

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

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

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