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.

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

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

AUTH_ERROR - The server cannot authenticate.

NOT_FOUND - The requested resource/business entity does not exist. The resource might also be hidden for security reasons.

RATE_LIMIT_EXCEEDED - Too many requests have been sent in a given amount of time. Intended for use with rate limiting schemes. 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.

MISSING_PARAMETER - A required field is missing.

INVALID_PARAMETER - The value provided for one or more request parameters is considered invalid.

REQUEST_TIMEOUT - Request timeout.

UNKNOWN_ERROR - Unknown error.

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.
• Paze is free to change this message at any point of time.
• 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.