Responses

The Paze® JavaScript SDK methods return either successful results or errors. These responses should be read from the client’s browser and logged to aid in appropriate workflows, error messaging, or investigations during development.

Successful Responses

A successful response means that the Promise is fulfilled. The action relating to the Promise has succeeded.

Error Responses

An error response means that the Promise is rejected. The action relating to the Promise has failed. Errors can be Business Errors or Standard Errors. An error object is passed for every error. The structure of the error is described in the following section.

Standard errors can be returned by any SDK method and should be handled in a common way. Business errors are returned by some SDK methods only and are described in the Errors section for each method.

Error Structure

This is the Standard Response Structure, which will be returned in case of an error. Use the error.reason field to drive error-handling logic. Errors are also provided with a human-readable error description in the error.message field. This field should be used only to understand the problem.

Error Structure Data Elements

The following structure details the Error Structure object.

message string optional

Every error should have a human-readable message describing the error. The message can vary even for the same reason, thus providing additional insights about the problem. This field should be used together with the Merchant’s own validation and error-handling processes. While Paze provides standardized error responses, Merchants are still responsible for detecting issues that originate from their own integration or business logic.

Paze is free to change the message at any time. Merchants should not use this field to drive their business logic or to expose it directly to Customers via UI or other means.

reason string required

Merchants should use this field to drive their error handling business logic.

details List(Object) optional

Array of field-level error objects. Data validation errors use this field to specify which fields failed validation using the location field. Returned only when one or more input fields fail validation during request processing.

details.location string required

The value of this field uses an XPath expression to point to the field that failed validation.

details.message string optional

Specific validation error message for this field.

Error Structure Data Elements Code Example

{
  "reason": "INVALID_PARAMETER", // Required: String for Merchant error handling mechanics
  "message": "Input parameters validation failed.", // Optional: String for readable description of the error.
  // Optional: List(Object) of data validation errors
  "details": [
    {
      "location": "creditCard", // Required: String XPath pointer to failure
      "message": "Should be a numeric value" // Optional: String specific error for field
    }
  ]
}

Standard Error Reason Codes

These errors can be returned by any SDK method and should be handled consistently in a unified way. Standard Errors are not documented as part of each individual method description.

This table is arranged in a processing order hierarchy. When testing, code that fails will only generate the first error encountered before the entire request is canceled.

UNABLE_TO_CONNECT - Unable to connect to Paze services. Retry the connection. If retrying fails, present Customers with a non Paze checkout option.

SERVER_ERROR - General server error. Resubmit the request. If retrying fails, present Customers with a non Paze checkout option.

SERVICE_ERROR - An error occurred with an internal Paze service. The platform will automatically retry. If this error is still received, present Customers with a non Paze checkout option.

AUTH_ERROR - The server cannot authenticate. Treat this as a configuration or credential issue. Do not retry repeatedly. Log the error, stop the Paze flow for this attempt, and present Customers with a non Paze checkout option while the integration issue is investigated.

NOT_FOUND - The requested resource or business entity does not exist, or may be hidden for security reasons. Do not retry automatically unless the request context changes. Log the error and present Customers with a non Paze checkout option.

RATE_LIMIT_EXCEEDED - Too many requests have been sent in a given amount of time. Wait before sending the next request and decrease the rate at which requests are sent. Consider implementing exponential backoff. In this algorithm, the delay before re-try is defined as:

// Exponential backoff for retrying failed requests
//
// Parameters:
//   retryCount    → Number (0, 1, 2, 3, ...)


function getRetryDelay(retryCount) {
  const randomDelayMs = Math.floor(Math.random() * 1000); // 0–1000 ms jitter
  const retryDelay = Math.pow(2, retryCount) * 1000 + randomDelayMs;
  return retryDelay; // delay in milliseconds
}

INVALID_REQUEST - The submitted request does not exist. Treat this as an integration error. Log the error, do not retry automatically, and correct the request structure before sending it again.

MISSING_PARAMETER - A required field is missing. Treat this as an integration or request-construction error. Log the error, do not retry automatically, and correct the request before sending it again.

INVALID_PARAMETER - One or more request parameter values are invalid. Treat this as a validation or integration error. Review the error.details field when present, correct the invalid inputs, and then retry only after the request has been fixed.

REQUEST_TIMEOUT - The request timed out. Retry the request when appropriate. If retrying fails, present Customers with a non Paze checkout option.

UNKNOWN_ERROR - An unknown error occurred. Log the error and use catch-all error handling. Avoid repeated retries; if the issue persists, present Customers with a non Paze checkout option.

Error Handling

This section provides a set of guidelines on how to handle errors for the purpose of simplifying error handling logic and achieving backward compatibility with newer versions of the SDK. It is assumed that the Merchant follows these guidelines.

• Drive error-handling logic based on the value of the error.reason field.
• Field error.message is for informational purposes only and may be subject to change.
• Do not parse this field to drive error handling logic.
• Do not expose this field to the Customer.
• It is assumed that there is a default "catch-all" type of error handling logic. Any errors with codes INVALID_REQUEST or MISSING_PARAMETER status codes are considered integration errors. Merchants can choose to show a message or simply fail to process this operation.