Error & Warning Dictionary

Reference for all error codes and warnings returned by the WickiePay API.

HTTP Status Codes

Code	Meaning
200	Success
201	Created
400	Bad Request — Invalid parameters
401	Unauthorized — Invalid or missing authentication
403	Forbidden — Insufficient permissions
404	Not Found — Resource doesn't exist
409	Conflict — Resource already exists or state conflict
422	Unprocessable — Valid format but invalid content
429	Too Many Requests — Rate limit exceeded
500	Internal Server Error

Error Response Format

{
  "error": {
    "code": "PAYMENT_EXPIRED",
    "message": "The payment has expired and can no longer be processed",
    "details": {
      "paymentId": "pay-uuid-123",
      "expiredAt": "2026-01-15T10:30:00Z"
    }
  }
}

Payment Errors

Code	Description	Resolution
PAYMENT_EXPIRED	Payment expired before receiving funds	Create a new payment
PAYMENT_UNDERPAID	Insufficient amount received	Accept partial or wait for remainder
PAYMENT_NOT_FOUND	Payment UUID doesn't exist	Verify the UUID
PAYMENT_ALREADY_COMPLETE	Attempting to modify a completed payment	No action needed
PAYMENT_CANCELLED	Payment was already cancelled	Create a new payment
INVALID_AMOUNT	Amount is zero, negative, or exceeds limits	Check amount value
INVALID_CURRENCY	Currency code not supported	See Supported Assets
INVALID_REFERENCE	Reference is missing or duplicate	Provide a unique reference

Authentication Errors

Code	Description	Resolution
INVALID_SIGNATURE	Request signature verification failed	Check key pair and signing logic
EXPIRED_SIGNATURE	Signature timestamp too old	Sync server clock (NTP)
INVALID_CLIENT_ID	Client ID not recognized	Verify API key registration
IP_NOT_WHITELISTED	Request from non-whitelisted IP	Update IP whitelist in portal
INSUFFICIENT_PERMISSIONS	API key lacks required role	Check role assignments

Channel Errors

Code	Description	Resolution
CHANNEL_NOT_FOUND	Channel UUID doesn't exist	Verify the UUID
CHANNEL_INACTIVE	Channel is disabled	Reactivate in portal
INVALID_CHANNEL_CONFIG	Invalid channel configuration	Check currency and settings

Compliance Errors

Code	Description	Resolution
SCREENING_BLOCKED	Transaction blocked by compliance screening	Contact compliance team
TRAVEL_RULE_REQUIRED	Missing Travel Rule information	Provide complianceDetails
KYC_REQUIRED	Customer KYC verification needed	Complete KYC process

Rate Limiting

Endpoint	Limit
Payment creation	100 requests/minute
Payment queries	500 requests/minute
Rate queries	1000 requests/minute
Webhook management	50 requests/minute

When rate limited, the response includes:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1705315500