Errors, limits and operations

Two kinds of failure

UniPay understood the request but won’t carry it out — a bill that doesn’t exist, a currency the provider doesn’t accept, a payment date out of range. These answer HTTP 200 with successful: false and a message:

{ "successful": false, "message": "Bill 'INV10023' not found. Cannot process payment.", "isNewRecord": true }

Always check successful, not just the HTTP status. Show or log the message, but don’t match on its exact wording, which may be improved over time. Sending the same request again gets the same answer.

The request itself failed — reported with an HTTP status:

Status	Body	Meaning	What to do
400	Error object	The request couldn’t be read, or a field is invalid.	Fix the request.
401	Empty	Token missing, invalid or expired.	Get a new token and retry once.
403	Empty	Your token lacks the scope this call needs.	Request the scope, or ask your Axis contact to enable it.
403	Error object	Your organisation can’t use this endpoint. code Authorization:PartnerTypeMismatch means payment-processor credentials called a service-provider endpoint, or the reverse.	Check you’re using the right credentials.
404	Empty	Wrong URL.	Check the path.
429	Empty	Rate limit exceeded.	Wait, then retry with backoff.
500, 502, 503, 504	Varies	UniPay can’t complete the request right now.	Retry with backoff — a payment retried with the same rrn is never recorded twice.

The error object looks like this; validationErrors lists each invalid field:

{
  "error": {
    "code": null,
    "message": "Your request is not valid!",
    "details": "The following errors were detected during validation.\r\n - The Description field is required.\r\n",
    "validationErrors": [
      { "message": "The Description field is required.", "members": ["description"] }
    ]
  }
}

Business messages

Every successful: false message the partner endpoints return. X stands for the value you sent.

Looking up a bill

Message	Cause
Bill 'X' not found	No bill with that number.
Bill number is required	Empty billNo.
Bill number must be at least 4 characters · Bill number cannot exceed 50 characters	Wrong length.
Bill number can only contain letters and numbers	Other characters after spaces, dashes and dots are removed.
Currency must be a 3-letter ISO 4217 code	Malformed currency.
Provide either a bill number or a service provider and account number, not both	lookup got both.
Provide a bill number, or a service provider and account number	lookup got neither.
Service provider is required · Account number is required	Account lookup missing a field.
Service provider cannot exceed 50 characters · Account number cannot exceed 64 characters · Account number must contain letters or digits	Malformed account lookup.
Service provider 'X' not found	Unknown provider number or short code.
Service provider short code 'X' is ambiguous; use the provider number	Use the number.
No outstanding bill found and no account on record for this number	Status 0 — NotFound.
Account standing is stale; no current information for this number	Status 3 — Unknown. Don’t take payment.

Paying a bill

Message	Cause
Bill 'X' not found. Cannot process payment.	No bill with that number.
No bill found for that account. Cannot process payment.	Account payment: no bill on the account.
Currency 'X' is not accepted by this service provider. Accepted currencies: …	See Currencies.
Invoice has expired	The bill’s expiryDate has passed.
Payment would exceed the remaining balance on this invoice	Overpayment, where the provider refuses them.
Payment date is required · Payment date cannot be in the future · Payment date cannot be more than 90 days in the past	Check paymentDate and its offset.
Bill number or account number is required · Bill number can only contain letters and numbers · Account number must not exceed 50 characters	Fix the bill or account.
Service provider is required when paying by account number	Add serviceProvider.
Service provider 'X' not found · Service provider short code 'X' is ambiguous; use the provider number	Fix serviceProvider.
RRN 'X' was already used for a different payment	One of your own rrn values reused for a different bill, account, amount or currency.
Retrieval Reference Number is required · RRN must not exceed 50 characters	Fix rrn.
Payment amount must be greater than zero · Currency must be 3 characters	Fix the field.

Success messages: Payment Saved for a new payment; Duplicate notification; already processed. when UniPay already had the rrn (isNewRecord: false) — both are success.

Reporting a day settlement

Every refusal is listed in Day settlements. Success messages: Settlement balanced — all payments matched. and Settlement accepted with N difference(s). — both mean the settlement was recorded.

Publishing a bill

Message	status	Cause
Added	Created	New bill.
Updated	Updated	Existing bill changed.
Bill number 'X' already exists for currency C.	AlreadyExists	Unchanged; nothing to do. successful is true.
Bill number 'X' already has payments and cannot be updated automatically.	Blocked	Raise a new bill instead.
Too many bills for a synchronous bulk create; submit in smaller chunks.		More than 500 in one bills call — use an import.

Rate limits

Endpoint	Limit
POST /connect/token	10 requests a minute
/api/app/payment-processor/*	60 requests a minute
All other /api/*	300 requests a minute

Limits are counted per client IP address: every process calling from the same address shares them. Over the limit you get 429 with no body — pause and retry with backoff. Caching your access token for its full 30 minutes keeps you well clear of the token limit. If you need more throughput, talk to your Axis contact.

Timeouts

Set a 10-second connect timeout and a 30-second read timeout. UniPay normally answers in well under a second.

Health

Endpoint	Answers
GET /api/app/health/live	200 {"status": "UP"} while UniPay is running.
GET /api/app/health/ready	200 with status HEALTHY or DEGRADED, or 503 with UNHEALTHY, after checking its database and services.

Neither needs a token. Use them to tell “UniPay is down” apart from “my request is wrong” — not as a substitute for handling errors on each call.