Responses

Successful Responses

A successful response means that the Promise is fulfilled and the requested action has succeeded.

Error Responses

An error response means that the Promise is rejected and the requested action has failed. API errors can be either Business Errors or Standard Errors. An error object is passed for every error. The structure of the error is described below.

Standard errors can be returned by any API and should be handled uniformly. Business errors are returned by some APIs only and are described in the API-specific Errors section.

Error Structure

This is the Standard Response Structure returned in case of an error. Use the error.reason field to drive error handling logic. The error.message field provides a human-readable description of the error but should not be parsed for logic.

Error Structure Data Elements

Error Structure Data Elements

Seq. #	Element Name	Element Type	Element Usage	Description
1	message	String	Optional	Every error should have a human-readable message describing the error. This message may vary and is for informational purposes only.
2	reason	String	Required	Use this field to drive error handling business logic.
3	details	Object	Optional	Array of fields specifying which fields failed validation.
4	details.location	String	Required	XPATH expression pointing to the field that failed validation.
5	details.message	String	Optional	Specific error message for this field.

Error Structure Data Elements Code Example

dictionary error {
  "message": "Input parameters validation failed.",
  "reason": "invalidParameter",
  "details": [
    {
      // Optional structure for input data validation 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.

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 internal Paze^SM service error occurred. 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 or business entity does not exist or may be hidden for security reasons.
RATE_LIMIT_EXCEEDED	Too many requests have been sent in a given amount of time. Wait before sending the next request and consider implementing Exponential Backoff.
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 invalid.
REQUEST_TIMEOUT	Request timeout.
UNKNOWN_ERROR	Unknown error.

Error Handling Guidelines

Drive error handling logic based on the value of the error.reason field.
- The error.message is for informational purposes only.
- Paze may change this message at any time; do not parse it for logic.
- Do not expose error.message to consumers.
Assume a default “catch-all” error handling mechanism. Errors with codes INVALID_REQUEST or MISSING_PARAMETER are considered integration errors.