Skip to main content

​
HTTP Status Codes

CodeMeaningWhen
200SuccessGET, PATCH operations
201CreatedPOST operations that create resources
400Bad RequestValidation failures, business logic errors
401UnauthorizedMissing or invalid API key
402Payment RequiredInsufficient wallet balance
403ForbiddenSuspended or pending partner account
404Not FoundResource doesn’t exist or doesn’t belong to you
422Unprocessable EntityRequest body validation errors
429Too Many RequestsRate limit exceeded
500Internal Server ErrorUnexpected server error

​
Error Response Format

All errors follow this shape: 
{
  "status": "error",
  "message": "ERROR_CODE",
  "data": {
    "error": "Human-readable description"
  }
}

​
Error Codes

​
User Errors

CodeHTTPDescription
DUP_USER400A user with this email already exists
USER_NOT_FOUND400The specified user service ID doesn’t exist
USER_NOT_APPROVED400User hasn’t completed KYC verification
USER_BLACKLISTED400User has been blacklisted

​
Card Errors

CodeHTTPDescription
CARD_NOT_FOUND404The specified card service ID doesn’t exist
CARD_ALREADY_FROZEN400Card is already frozen
CARD_ALREADY_TERMINATED400Card has been terminated and cannot be modified
CARD_IS_ACTIVE400Card is active (when trying to unfreeze an active card)
CARD_CREATION_LIMIT400Only 1 card can be created per user every 5 minutes
CARD_DEBIT_LIMIT429Card debit rate limit exceeded
INVALID_PROGRAM400Invalid card program for this operation

​
Wallet Errors

CodeHTTPDescription
INSUFFICIENT_WALLET_BALANCE402Partner wallet doesn’t have enough funds
INSUFFICIENT_FUNDS400Insufficient collateral balance for card operation

​
Transaction Errors

CodeHTTPDescription
TRANSACTION_NOT_FOUND404The specified transaction ID doesn’t exist

​
General Errors

CodeHTTPDescription
PARTNER_NOT_FOUND404Partner account not found
INTERNAL_ERROR500An unexpected server error occurred

​
Idempotency Errors

When using the idempotency-key header:
ScenarioHTTPMessage
Same key + same body (duplicate request)400Idempotency key has already been used
Same key + different body400Duplicate 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"
    ]
  }
}