Errors - PLU Card API

HTTP Status Codes

Code	Meaning	When
`200`	Success	GET, PATCH operations
`201`	Created	POST operations that create resources
`400`	Bad Request	Validation failures, business logic errors
`401`	Unauthorized	Missing or invalid API key
`402`	Payment Required	Insufficient wallet balance
`403`	Forbidden	Suspended or pending partner account
`404`	Not Found	Resource doesn’t exist or doesn’t belong to you
`422`	Unprocessable Entity	Request body validation errors
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Unexpected server error

Error Response Format

All errors follow this shape:

{
  "status": "error",
  "message": "ERROR_CODE",
  "data": {
    "error": "Human-readable description"
  }
}

Error Codes

User Errors

Code	HTTP	Description
`DUP_USER`	400	A user with this email already exists
`USER_NOT_FOUND`	400	The specified user service ID doesn’t exist
`USER_NOT_APPROVED`	400	User hasn’t completed KYC verification
`USER_BLACKLISTED`	400	User has been blacklisted

Card Errors

Code	HTTP	Description
`CARD_NOT_FOUND`	404	The specified card service ID doesn’t exist
`CARD_ALREADY_FROZEN`	400	Card is already frozen
`CARD_ALREADY_TERMINATED`	400	Card has been terminated and cannot be modified
`CARD_IS_ACTIVE`	400	Card is active (when trying to unfreeze an active card)
`CARD_CREATION_LIMIT`	400	Only 1 card can be created per user every 5 minutes
`CARD_DEBIT_LIMIT`	429	Card debit rate limit exceeded
`INVALID_PROGRAM`	400	Invalid card program for this operation

Wallet Errors

Code	HTTP	Description
`INSUFFICIENT_WALLET_BALANCE`	402	Partner wallet doesn’t have enough funds
`INSUFFICIENT_FUNDS`	400	Insufficient collateral balance for card operation

Transaction Errors

Code	HTTP	Description
`TRANSACTION_NOT_FOUND`	404	The specified transaction ID doesn’t exist

General Errors

Code	HTTP	Description
`PARTNER_NOT_FOUND`	404	Partner account not found
`INTERNAL_ERROR`	500	An unexpected server error occurred

Idempotency Errors

When using the idempotency-key header:

Scenario	HTTP	Message
Same key + same body (duplicate request)	400	Idempotency key has already been used
Same key + different body	400	Duplicate Idempotency key

Validation Errors (422)

When request body validation fails, the response includes field-level errors:

{
  "status": "error",
  "message": "Validation failed",
  "data": {
    "error": [
      "firstName must be between 1 and 100 characters",
      "email must be a valid email address"
    ]
  }
}

​HTTP Status Codes

​Error Response Format

​Error Codes

​User Errors

​Card Errors

​Wallet Errors

​Transaction Errors

​General Errors

​Idempotency Errors

​Validation Errors (422)

HTTP Status Codes

Error Response Format

Error Codes

User Errors

Card Errors

Wallet Errors

Transaction Errors

General Errors

Idempotency Errors

Validation Errors (422)