Error Codes

Response Format

All error responses follow a consistent format:

{
  "message": "Human-readable error description."
}

Validation errors include field-level details:

{
  "message": "Validation failed.",
  "errors": {
    "field_name": ["Error description."]
  }
}

HTTP Status Codes

Status	Name	Description
200	OK	Request succeeded
201	Created	Resource created successfully (e.g., voucher generated)
401	Unauthorized	Invalid or expired token, or wrong credentials
403	Forbidden	IP not whitelisted or account disabled
404	Not Found	Resource not found (e.g., user with given phone number)
409	Conflict	Duplicate external_transaction_id on deposit
422	Unprocessable Entity	Validation error or daily limit exceeded
429	Too Many Requests	Rate limit exceeded --- wait before retrying

Common Error Scenarios

Invalid or Expired Token

// Status: 401
{
  "message": "Invalid credentials."
}

Solution: Request a new token via the authentication endpoint.

IP Not Whitelisted

// Status: 403
{
  "message": "Access denied."
}

Solution: Contact the Academia team to whitelist your server's IP address.

Daily Limit Exceeded

// Status: 422
{
  "message": "Daily limit exceeded.",
  "daily_max_amount": 5000,
  "used_today": 4950,
  "remaining": 50,
  "requested": 100
}

Solution: Wait until the next day when your daily limit resets, or contact the Academia team to increase your limit.

Duplicate Deposit

// Status: 409
{
  "message": "Duplicate transaction.",
  "external_transaction_id": "RUNPAY-TXN-12345"
}

Solution: This transaction was already processed. Use a different external_transaction_id for new transactions.

Rate Limited

// Status: 429
{
  "message": "Too many requests."
}

Solution: Wait a moment before retrying. Consider adding a delay between requests in your integration.

Validation Error

// Status: 422
{
  "message": "Validation failed.",
  "errors": {
    "denomination_id": ["The selected denomination id is invalid."]
  }
}

Solution: Check your request parameters against the API documentation.