Errors

📘

Note:

In general, the Partner API will return an HTTP 200 OK response for successful requests. If an error occurs, the API will respond with one of the following status codes:

4XX Client Error: Indicates an error on the client side, such as invalid input or unauthorized access. Review your request parameters and authentication details to resolve these issues.

5XX Server Error: Indicates an error on the server side. These errors are temporary and may resolve on their own, but if they persist, please contact support.

Error Object

General structure for an error given by the partner API:

{
  "code":string,
  "message":string
}

• code: This is a unique, predefined error identifier that corresponds to specific issues the API may encounter. Unlike an HTTP status code, this code provides more granular information about the exact nature of the error, making it easier to detect and handle specific issues programmatically. Each error code has a descriptive identifier, such as:
  • unauthorizedAccess: The client’s credentials are either missing, invalid, or do not have the necessary permissions.
  • paymentSessionInProgress: The device is already handling a payment, so a new payment cannot be initiated until the current one is completed or canceled.
  • connectedDeviceNotFound: The specified device is either not connected to the internet or not set to the required mode for the requested action.
    These unique codes allow clients to write precise error-handling logic for various scenarios without relying on parsing the message.
• message: This field contains a human-readable description of the error. It is intended to provide details on what caused the issue and, if applicable, how to resolve it. The message is especially helpful for debugging and understanding specific causes of failures. Examples:
  • "Invalid input: missing required field 'amount'"
  • "Unauthorized access: API key is invalid"
  • "A payment is already in progress. Please complete or cancel the current payment before initiating a new one."

Together, the code and message fields allow developers to handle errors gracefully by understanding the nature of the error (code) and displaying helpful information to users or logging detailed messages (message) for troubleshooting.

Example Error Object

An error response object might look like this if a user attempts to initiate a payment while one is already in progress:

{  
  "code": "paymentSessionInProgress",  
  "message": "The device is already handling a payment. Either cancel the initial payment directly from the terminal or use the 'abort payment' API endpoint. Once completed, try again."  
}

This structure provides developers with both the precise error code for handling specific errors programmatically and the detailed message for improved clarity and troubleshooting.

List of All Optional Errors