Error codes

Elite Neo Bank APIs use standard HTTP status codes along with structured API responses to indicate request status, authentication issues, validation failures, transaction errors, and system-level failures. Merchants should always validate:

HTTP status codes
API response codes
Response messages
Transaction status values

Proper error handling helps build stable, secure, and reliable integrations.

Standard Error Response Format

{
  "status": false,
  "code": 401,
  "message": "Invalid signature."
}

HTTP Status Codes

HTTP Code	Meaning
`200`	Request processed successfully
201	Request created successfully
`400`	Bad request or invalid payload
`401`	Authentication failed
`403`	Access denied
`404`	Resource or transaction not found
`409`	Duplicate request conflict
`422`	Validation or business logic failure
`429`	Too many requests
`500`	Internal server error
`503`	Service temporarily unavailable

Authentication Errors

401 Unauthorized

Occurs when API authentication fails.

Possible Reasons

Invalid API key
Incorrect signature
Expired timestamp
Missing authentication headers

Example Response

{
  "status": false,
  "code": 401,
  "message": "Invalid signature."
}

Invalid Wallet ID

403 Forbidden

Occurs when wallet credentials do not belong to the selected environment.

Possible Reasons

Sandbox wallet used in production
Production wallet used in Sandbox
Invalid merchant wallet

Example Response

{
  "status": false,
  "code": 403,
  "message": "Invalid wallet ID for selected environment."
}

Transaction Not Found

404 Not Found

Occurs when the requested transaction or order does not exist.

Possible Reasons

Invalid order ID
Invalid payout order ID
Transaction does not exist
Incorrect merchant credentials

Example Response

{
  "status": false,
  "code": 404,
  "message": "Payout transaction not found."
}

Validation Errors

400 Bad Request

Occurs when request payload validation fails.

Possible Reasons

Missing required parameters
Invalid JSON payload
Incorrect request structure
Invalid data format

Example Response

{
  "status": false,
  "code": 400,
  "message": "Invalid request payload."
}

Insufficient Wallet Balance

422 Unprocessable Entity

Occurs when payout wallet balance is insufficient.

Possible Reasons

Wallet balance too low
Transfer amount exceeds available funds

Example Response

{
  "status": false,
  "code": 422,
  "message": "Insufficient wallet balance."
}

Duplicate Transaction Errors

409 Conflict

Occurs when duplicate transaction references are used.

Possible Reasons

Duplicate order_id
Duplicate payout_order_id
Repeated payout initiation

Example Response

{
  "status": false,
  "code": 409,
  "message": "Duplicate transaction request."
}

Rate Limit Errors

429 Too Many Requests

Occurs when API request limits are exceeded.

Possible Reasons

Excessive API traffic
Aggressive retry loops
Burst request patterns

Example Response

{
  "status": false,
  "code": 429,
  "message": "Too many requests."
}

Internal Server Errors

500 Internal Server Error

Occurs when an unexpected server-side failure happens.

Possible Reasons

Temporary infrastructure issue
Banking partner downtime
Internal processing error

Example Response

{
  "status": false,
  "code": 500,
  "message": "Internal server error."
}

Service Unavailable

503 Service Unavailable

Occurs during temporary maintenance or service interruptions.

Possible Reasons

Scheduled maintenance
Banking partner downtime
Temporary service outage

Example Response

{
  "status": false,
  "code": 503,
  "message": "Service temporarily unavailable."
}

Recommended Error Handling Workflow

Validate HTTP status code
Read API response message
Log request and response
Retry processing carefully if applicable
Verify transaction status using APIs
Avoid duplicate transaction creation

Retry Recommendations

Retry only for temporary errors such as:

Error	Retry Recommended
`429`	Yes
`500`	Yes
`503`	Yes
`PROCESSING` status	Yes
`401`	No
`403`	No
`404`	Limited
`422`	No

Logging Recommendations

Merchants should log:

Request payloads
API responses
Signature generation logs
Webhook payloads
Retry attempts
Transaction references

This helps simplify:

Debugging
Reconciliation
Compliance audits
Issue tracking

Security Recommendations

Never expose secret keys
Always use HTTPS
Validate webhook signatures
Generate fresh timestamps
Regenerate signatures for every retry

Best Practices

Handle all API errors gracefully
Avoid aggressive retry loops
Use idempotent transaction IDs
Verify transaction status server-side
Maintain detailed transaction logs

​Error codes

​Standard Error Response Format

​HTTP Status Codes

​Authentication Errors

​401 Unauthorized

​Possible Reasons

​Example Response

​Invalid Wallet ID

​403 Forbidden

​Possible Reasons

​Example Response

​Transaction Not Found

​404 Not Found

​Possible Reasons

​Example Response

​Validation Errors

​400 Bad Request

​Possible Reasons

​Example Response

​Insufficient Wallet Balance

​422 Unprocessable Entity

​Possible Reasons

​Example Response

​Duplicate Transaction Errors

​409 Conflict

​Possible Reasons

​Example Response

​Rate Limit Errors

​429 Too Many Requests

​Possible Reasons

​Example Response

​Internal Server Errors

​500 Internal Server Error

​Possible Reasons

​Example Response

​Service Unavailable

​503 Service Unavailable

​Possible Reasons

​Example Response

​Recommended Error Handling Workflow

​Retry Recommendations

​Logging Recommendations

​Security Recommendations

​Best Practices

Error codes

Standard Error Response Format

HTTP Status Codes

Authentication Errors

401 Unauthorized

Possible Reasons

Example Response

Invalid Wallet ID

403 Forbidden

Possible Reasons

Example Response

Transaction Not Found

404 Not Found

Possible Reasons

Example Response

Validation Errors

400 Bad Request

Possible Reasons

Example Response

Insufficient Wallet Balance

422 Unprocessable Entity

Possible Reasons

Example Response

Duplicate Transaction Errors

409 Conflict

Possible Reasons

Example Response

Rate Limit Errors

429 Too Many Requests

Possible Reasons

Example Response

Internal Server Errors

500 Internal Server Error

Possible Reasons

Example Response

Service Unavailable

503 Service Unavailable

Possible Reasons

Example Response

Recommended Error Handling Workflow

Retry Recommendations

Logging Recommendations

Security Recommendations

Best Practices