Error Reference

Errors are returned with an HTTP status code and a message:

{
  "status": 400,
  "message": "Decryption failed"
}

Authentication & access errors

HTTP	Message	Cause	Fix
400	`No token provided`	Missing `Authorization` header	Send `Authorization: Bearer <api key>`
400	`Invalid token prefix`	Key doesn’t start with `cngn_test`/`cngn_live`	Check you copied the full key
400	`Merchant not found`	API key not recognised	Regenerate the key in the dashboard
400	`No Test SSH Key found` / `No Live SSH Key found`	No Ed25519 public key uploaded for this environment	Upload your public key in the dashboard
403	`IP address not whitelisted`	Request came from a non-whitelisted IP	Add your server IP in dashboard security settings
403	`Could not determine client IP address`	Source IP could not be resolved	Check proxy configuration (`X-Forwarded-For`)
403	`Permission denied`	Your role lacks the required permission	See Permissions
404	`Merchant not found`	Business role could not be resolved	Contact support

Encryption errors

HTTP	Message	Cause	Fix
400	`Missing encryption data, key, or IV`	Body sent as plain JSON instead of `{content, iv}`	Encrypt the body; see Encryption
400	`Decryption failed`	Wrong AES key, malformed base64, or corrupted IV	Verify the encryption key and IV generation

Validation errors

Request bodies are validated after decryption. Validation failures return 400 with a field: message string, for example:

{
  "status": 400,
  "message": "amount: Number must be greater than or equal to 1"
}

Rate limiting

HTTP	Message	Fix
429	`Too many requests. Please try again later.`	Wait 60 seconds; see Rate Limiting

Service availability

HTTP	Message	Cause
400	`Service is currently unavailable. Please try again later.`	Redeem or withdrawal service temporarily disabled platform-wide

Business-logic errors

Endpoint-specific failures (insufficient balance, invalid bank account, unsupported network, etc.) also return 400 with a descriptive message. Treat any unrecognised 400 message as non-retryable without changing the request.

Retry guidance: retry 429 (after the block window) and 5xx with exponential backoff. Do not blindly retry 400 responses on money-moving endpoints. Verify state first with Verify Withdrawal or Get Transactions to avoid duplicate transfers.

Get Started

Integration Guides

Authentication & access errors

Encryption errors

Validation errors

Rate limiting

Service availability

Business-logic errors

​Authentication & access errors

​Encryption errors

​Validation errors

​Rate limiting

​Service availability

​Business-logic errors

Authentication & access errors

Encryption errors

Validation errors

Rate limiting

Service availability

Business-logic errors