LakiConnect

Error handling

Standard Error Response

All errors follow a consistent structure:

JSONjson

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request body is invalid.",
    "details": [
      {
        "field": "business.tin",
        "issue": "TIN must be 10 digits."
      }
    ]
  },
  "request_id": "req_1a2b3c4d5e6f"
}

HTTP Status Codes

Success

Request completed as expected.

200

OK

Common causes: Request succeeded.

Process the response body.

201

Created

Common causes: Resource created successfully.

Store the returned resource ID if needed.

Client errors

Fix the request — retries will not help without changes.

400

Bad Request

Common causes: Missing required fields or invalid format.

Fix the request payload before retrying.

401

Unauthorized

Common causes: Missing or invalid API key.

Verify your X-API-Key header.

403

Forbidden

Common causes: API key lacks required permissions.

Check RBAC scopes or contact support.

404

Not Found

Common causes: Resource ID does not exist or does not belong to this master.

Confirm the ID and connected-merchant context.

409

Conflict

Common causes: Duplicate idempotency key with different parameters.

Reuse the same key with identical params, or use a new key.

422

Unprocessable Entity

Common causes: Request is well-formed but semantically invalid.

Review field values against API constraints.

429

Too Many Requests

Common causes: Rate limit exceeded.

Wait for Retry-After, then retry with backoff.

Server errors

Transient failures — safe to retry with backoff.

500

Internal Server Error

Common causes: Unexpected server-side error.

Retry with exponential backoff; log request_id.

Common Error Codes

Authentication & permissions

Issues with API keys or access scopes.

UNAUTHORIZED

API key is missing or invalid.

Send a valid X-API-Key header with every request.

FORBIDDEN

Insufficient RBAC permissions.

Use a key with the required scope or contact your account admin.

Resources & merchants

Missing or unlinked entities in your platform.

NOT_FOUND

The requested resource does not exist.

Verify the resource ID and that it belongs to your master account.

CONNECTED_MERCHANT_NOT_FOUND

X-Connected-Merchant-ID is not linked to this master.

Onboard the merchant or use the correct connected-merchant header value.

Validation & configuration

Request or account state does not meet API requirements.

VALIDATION_ERROR

One or more request fields failed validation.

Inspect error.details for field-level issues and correct the payload.

KYC_NOT_APPROVED

Payment attempted on a connected account that is not KYC-approved.

Wait for KYC approval or block payments until status is approved.

FEE_CONFIG_NOT_SET

No fee config found for master or connected account.

Configure a default or per-connected fee rule before processing payments.

Conflicts & rate limits

Retryable or idempotency-related request issues.

RATE_LIMITED

Request rate limit exceeded; retry after the indicated interval.

Honor Retry-After when present; otherwise back off and retry.

IDEMPOTENCY_CONFLICT

Same idempotency key reused with different request parameters.

Use a new idempotency key, or replay with identical request body.

Retry Recommendations

Network errors (5xx): Retry with exponential backoff. Start with a 1-second delay and double on each attempt (max 5 attempts).
Rate limits (429): Respect the Retry-After header if present. Otherwise wait at least 1 second before retrying.
Client errors (4xx): Do not retry without fixing the request. Log request_id for debugging.

Continue

API reference

Next section in this guide.