Error Codes

Reference for all API error codes and their meanings.

HTTP Status Codes

WiaPay API uses conventional HTTP status codes to indicate the success or failure of requests.

Status Code	Meaning	Description
`200`	OK	Request succeeded
`201`	Created	Resource created successfully
`400`	Bad Request	Invalid request parameters or body
`401`	Unauthorized	Invalid or missing authentication
`403`	Forbidden	Access denied (IP not whitelisted, etc.)
`404`	Not Found	Resource not found
`409`	Conflict	Duplicate resource (e.g., transaction ID)
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Server error (contact support)

Error Response Format

All error responses follow a consistent JSON format:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message"
  },
  "timestamp": 1705320000
}

Error Codes

Authentication Errors (401)

Code	Description	Solution
`MISSING_API_KEY`	X-API-Key header not provided	Include X-API-Key header in your request
`INVALID_API_KEY`	API key is invalid or disabled	Check your API key or contact support
`MISSING_SIGNATURE`	X-Signature header not provided	Include X-Signature header in your request
`INVALID_SIGNATURE`	Signature verification failed	Check your signature generation logic
`MISSING_TIMESTAMP`	X-Timestamp header not provided	Include X-Timestamp header in your request
`INVALID_TIMESTAMP`	Timestamp format is invalid	Use Unix timestamp in seconds
`TIMESTAMP_EXPIRED`	Request timestamp is too old (>5 min)	Use current timestamp, sync server clock

Authorization Errors (403)

Code	Description	Solution
`SITE_INACTIVE`	Your account is suspended or inactive	Contact support to reactivate your account
`IP_NOT_WHITELISTED`	Request IP is not in whitelist	Add your server IP to the whitelist
`INSUFFICIENT_BALANCE`	Not enough balance for withdrawal	Deposit funds or reduce withdrawal amount

Validation Errors (400)

Code	Description	Solution
`VALIDATION_ERROR`	Request body validation failed	Check required fields and data types
`INVALID_AMOUNT`	Amount is invalid (negative, zero, etc.)	Provide a positive number
`AMOUNT_OUT_OF_RANGE`	Amount outside bank limits	Check min/max limits from available-banks
`INVALID_BANK`	Bank ID not found or inactive	Use valid bank ID from available-banks
`INVALID_IBAN`	IBAN format is invalid	Verify IBAN format (TR + 24 digits)
`INVALID_CURRENCY`	Currency not supported	Use supported currency (TRY)

Resource Errors (404, 409)

Code	HTTP	Description	Solution
`TRANSACTION_NOT_FOUND`	404	Transaction ID not found	Verify transaction ID exists
`BANK_NOT_FOUND`	404	Bank not found or unavailable	Use ID from available-banks endpoint
`DUPLICATE_TRANSACTION`	409	processId already exists	Use a unique transaction ID

Server Errors (500)

Code	Description	Solution
`INTERNAL_SERVER_ERROR`	Unexpected server error	Retry request; contact support if persists
`SERVICE_UNAVAILABLE`	Service temporarily unavailable	Retry after a few minutes

Example Error Responses

401 - Invalid Signature

{
  "success": false,
  "error": {
    "code": "INVALID_SIGNATURE",
    "message": "Signature verification failed"
  },
  "timestamp": 1705320000
}

400 - Validation Error

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "processId and amount are required"
  },
  "timestamp": 1705320000
}

403 - IP Not Whitelisted

{
  "success": false,
  "error": {
    "code": "IP_NOT_WHITELISTED",
    "message": "Your IP address is not whitelisted"
  },
  "timestamp": 1705320000
}

409 - Duplicate Transaction

{
  "success": false,
  "error": {
    "code": "DUPLICATE_TRANSACTION",
    "message": "Transaction with this processId already exists"
  },
  "timestamp": 1705320000
}

Error Handling Best Practices

Recommendations

Always check the success field in responses
Log error codes and messages for debugging
Implement retry logic with exponential backoff for 5xx errors
Don't retry 4xx errors without fixing the request
Show user-friendly error messages to customers
Monitor error rates and alert on anomalies

Error Handling Example (JavaScript)

async function createTransaction(data) {
  try {
    const response = await fetch('/v1/deposit', {
      method: 'POST',
      headers: { /* ... */ },
      body: JSON.stringify(data)
    });

    const result = await response.json();

    if (!result.success) {
      // Handle specific error codes
      switch (result.error.code) {
        case 'DUPLICATE_TRANSACTION':
          // Transaction already exists, maybe return existing one
          return handleDuplicateTransaction(data.processId);

        case 'AMOUNT_OUT_OF_RANGE':
          throw new Error('Amount must be between min and max limits');

        case 'INVALID_SIGNATURE':
          // Log and alert - this shouldn't happen in production
          console.error('Signature error - check implementation');
          throw new Error('Authentication error');

        default:
          throw new Error(result.error.message);
      }
    }

    return result.data;
  } catch (error) {
    // Handle network errors
    if (error.name === 'TypeError') {
      // Network error - maybe retry
      console.error('Network error:', error);
    }
    throw error;
  }
}