Responses

Where outlined, Paze returns either successful responses or error responses. 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. API 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 API and should be handled in a common way. Business errors are returned by some APIs only and are described in the Errors section for each API.

Error Structure

This is the Standard Response Structure, which will be returned in case of an error. Use 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 approach should be used along with Merchant bugs to avoid introducing new reasons and still provide enough information to fix the bug.

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 consumers via UI or other means.

reason String Optional

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

details Objects Optional

Array of fields - Data validation errors will use this field to specify which fields failed the validation using location field.

details.location String Required

The value of this field is using XPATH expression to point to the field that failed validation.

details.message Object String_ Optional

The specific 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.", // Required: String for readable description of the error. 
"details": [ // Optional: Object Array of data validation errors 
  { 
    "location": "creditCard", // Required: String XPath pointer to failure 
    "message": "Should be a numeric value" // Required: String specific error for field 
  } 
  ] 
}

Standard Error Reason Codes

These errors can be returned by any API and should be handled consistently in a unified way. Standard Errors are not documented as part of each individual API 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 APIs. Retry the connection. If retrying fails, present users with a non-Paze checkout.

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

SERVICE_ERROR - An error occurred with an internal Paze service.The APIs will automatically retry. If this error is received, present users 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 of sending API requests.

Consider implementing Exponential Backoff. In this algorithm, the delay before re-try is defined as:

• retryDelay = (2 ^ N) * 1000 + randomDelayMs
  • retryDelay Retry delay in milliseconds.
    • N retry count (0, 1, 2, 3, …)
      • randomDelayMs = random delay in milliseconds (0 .. 1000)
        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 API errors for the purpose of simplifying error handling logic and achieving backward compatibility with the newer versions of the APIs. It is assumed that the Merchant follows these guidelines.

• Drive error handling logic based on the value of 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 Consumer
• 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.