Errors#

An HTTP status describes the response at the transport level. The JSON envelope describes the application outcome. Inspect both. The existing KlemPay transport recognises responseCode values 00 and 000 as successful; an HTTP 200 with another code is handled as an unsuccessful operation.

{
  "responseCode": "PAYUSR-006",
  "responseMessage": "This invitation link is no longer valid. Ask for a new invitation",
  "errors": ["This invitation link is no longer valid. Ask for a new invitation"]
}

Display the backend's useful explanation in the affected form or page. Do not keep a loading indicator active after a rejected response, and do not replace a specific validation message with a generic success or unavailable state.

These are standard HTTP interpretations, not an endpoint-specific guarantee. Always read the application message and confirmed controller contract alongside the status.

The table distinguishes behaviour implemented in the existing KlemPay web project from codes whose backend definitions were not supplied. The backend responseMessage and endpoint schema remain authoritative.

Keep response codes as strings; converting 00 to a number destroys its exact representation. Validate that errors contains strings, preserve responseMessage, and validate successful responseData against the expected shape.

const successfulCodes = new Set(["00", "000"]);
const envelope = await response.json();
const messages = Array.isArray(envelope.errors)
  ? envelope.errors.filter((value) => typeof value === "string")
  : [];

if (!response.ok || !successfulCodes.has(envelope.responseCode)) {
  return {
    ok: false,
    message:
      typeof envelope.responseMessage === "string"
        ? envelope.responseMessage
        : "The request could not be completed.",
    errors: messages,
    responseCode: envelope.responseCode,
    httpStatus: response.status,
  };
}
return { ok: true, data: validateExpectedResponse(envelope.responseData) };

A non-JSON response, malformed envelope, or wrong successful data shape is a protocol failure. Show a recoverable service message, record redacted diagnostics, and do not treat it as a successful transaction.

Retry safe reads with a maximum attempt count and a short backoff. For writes, use the endpoint's documented idempotency mechanism and retrieve the original state when the outcome is uncertain.

Do not automatically retry validation, authentication, or permission errors without changing the cause. A duplicate-reference response requires reconciliation. A timeout requires an outcome check, not a new business intent.

When reporting an issue, include the environment, time, method, path, HTTP status, response code, sanitised response message, and returned trace identifier. Include the existing resource or operation reference only through an approved support channel.

Exclude API secrets, authorization headers, OTPs, full account numbers, personal identity data, and secret-bearing URLs. Support should be able to trace the request without receiving credentials.

• Field validation stays beside the related field or form.
• Access failures explain the next action without exposing internal permission rules.
• Pending writes show the original reference and a status-check action.
• Page-loading failures show the actual backend explanation and a retry action.
• Background refresh failures preserve already readable content and disclose that the refresh failed.
• Every loading state ends on success, empty data, rejection, timeout, or an unexpected transport failure.