Errors

Omniware returns errors as JSON with an error object instead of data:

{
  "error": {
    "code": 1023,
    "message": "Hash Mismatch"
  }
}

A successful response always has a top-level data object. A failed response always has a top-level error object. They never appear together.

Error categories

Validation errors (4xx semantics)

Caused by malformed input — missing required fields, bad hash, invalid amount, unknown order ID. Fix the request and retry. The most common is 1023 — Hash Mismatch, which usually means you forgot to skip an empty field or sorted on the wrong locale.

Authorization errors

Returned when your IP is not whitelisted or your api_key is wrong. Do not retry blindly — fix the credential or whitelist your IP first.

Not-found errors

Codes like 1028 — Transaction not found and 1050 — No data record found for the given input. These mean Omniware does not (yet) have a record matching your query. Retry with backoff in case the underlying transaction is still propagating.

Bank / network errors

Code 1029 — Transaction Terminated and friends. The bank or scheme could not complete the operation. Treat the original transaction as failed and retry with a fresh order_id / merchant_reference_number.

State errors

e.g. GEN-INVOICE-EXISTS, GEN-STATUS-INVALID. The resource is in a state that doesn't permit the operation. Fetch the latest state and decide whether to retry.

Retry policy

Symptom	Action
Network timeout, 5xx, no response	Check the matching status API first. Retry only with a reference that cannot create a duplicate operation.
1023 Hash mismatch	Do not retry. Fix the hash and resend.
1028 Transaction not found (right after a payment)	Retry 2–3× with 5–10s gaps. The lookup may lag the write.
1029 Transaction terminated	Treat as failed. Generate a new order_id if you want to try again.
1086 More than 50 records	Add page_number and per_page to the request.

Full code reference

See Reference → Error codes for the complete numeric table.