Errors

Zenith Payments uses standard HTTP response codes to indicate whether a request succeeded or failed. This page covers the cross-cutting error semantics — response shape, each status code's meaning in context, and operational guidance for handling failures.

For per-endpoint error responses with exact schemas and examples, see /openapi.

In general "status codes" in the 2XX range indicate success.

Whereas, "status codes" in the 4XX range indicate a client-side error, which means that there was a failure in the information provided (e.g., a missing parameter, unauthorised access etc.).

"Status codes" in the 5XX range indicate an error with Zenith Payment's internal servers. Please contact us if this occurs..

If the response code is not 2XX, it means the operation failed somehow and you may need to take action accordingly. You can check the response (which will be in JSON format) for a field called message which briefly explains the error reported.

{
  "message": "Invalid payment reference."
}

---

Status codes returned by the API

The following codes are the complete set of HTTP statuses the Zenith Payments REST API can return. Any status code not listed here is not used by the API.

Status Code	Error	Explanation
400	Bad Request	The request was unacceptable, often due to missing a required parameter.
401	Unauthorized	No valid API key provided.
402	Request Failure	The request has failed, however the variables were valid.
403	Forbidden	The API key does not have the the right permissions to perform the request.
404	Not Found	The requested resource doesn't exist.
409	Too Many Requests	The API request limit is exceeded. Please see section Rate Limiting for more info.
5XX	Server Error	ZenPay servers have failed to process your request.

---

Handling 500 responses safely

A 500 response does not guarantee the operation failed. The resource may or may not have been created, updated, or submitted. Never assume failure on a 500 and retry blindly — that can cause duplicate payments, duplicate customers, or duplicate tokens.

Safe handling pattern:

1. Do not immediately retry the same request. A second attempt with the same merchantUniquePaymentId or customerUniqueId may be rejected with a 409 Conflict — or worse, it may succeed and create a duplicate.
2. Query the resource using the merchant-supplied identifier (merchantUniquePaymentId, customerUniqueId, or similar). If it exists, the original request succeeded — treat the 500 as transient.
3. If the resource does not exist, it is safe to submit a new request.
4. Log the full response body and request ID and escalate to Zenith Payments support if the pattern repeats.

---

Debugging checklist

When investigating an error response:

1. Read the message field.
2. Note the HTTP status code and match it against the table above.
3. Capture the full request payload and response body.
4. Capture the request timestamp (UTC) and any merchant-side request identifier.
5. For 409 and 500 responses, check whether the resource already exists before retrying.
6. For 412 responses, check merchant configuration and the upstream provider.
7. For persistent 500 responses, escalate to Zenith Payments support with the captured context.

---

Related

• /openapi — per-endpoint response schemas and examples
• Common API Patterns — idempotency, identifier reuse, retry design
• Authentication — credential handling