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 invetigations 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.

Seq. #	Element Name	Element Type	Element Usage	Description
1	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.
2	reason	String	Required	Merchants should use this field to drive their error handling business logic.
3	details	Object	Optional	Array of fields - Data validation errors will use this field to specify which fields failed the validation using location field.
4	details.location	String	Required	The value of this field is using XPATH expression to point to the field that failed validation.
5	details.message	String	Optional	The specific error for this field.

Error Structure Data Elements Code Example

dictionary error {
    "message": "Input parameters validation failed.", 
    "reason": "invalidParameter", 
    "details": 
    [/ Optional structure, used with input data validation error
      {// Types to specify the fields with errors
         "location": "creditCard",  
         "message": "Should be a numeric value"  
      }
    ]
  }

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.

Standard Error Reason Codes

Reason Code	Description and What to Do
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.