Error Handling

Westpay offers a REST API for requesting terminal IDs in ECR integration. The API returns JSON responses. To handle responses effectively, clients should validate JSON structure, handle errors using status codes, and implement retries for network issues, enhancing reliability and user experience.

200 — Success

A successful response contains the requested data.

json
{
    "terminalId": "20001925",
    "password": "333333"
}

401 — Unauthorized

Returned when authentication credentials are missing, invalid, or expired.

json
{
    "statusCode": 401,
    "message": "You are not authorized.",
    "timestamp": "2023-08-22T14:38:30.097837Z"
}

Resolution: Ensure you are providing a valid Bearer token in the Authorization header, issued by Westpay.

400 — Validation Error

Returned when the request body fails validation.

json
{
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "traceId": "00-4ba3dec7425ae03d42a14acbe7f3bc98-5dd001e411fbf5c0-00",
    "errors": {
        "StoreId": [
            "The StoreId field is required."
        ]
    }
}

Resolution: Check the errors object for specific field-level validation messages and correct the request accordingly.

Other Error Status Codes (4xx / 5xx)

All other error responses use this common format:

json
{
    "statusCode": 422,
    "message": "Access to store information with store id 2011 is not authorized or store id 2011 is not on-boarded with any of authorized customer.",
    "timestamp": "2023-08-22T14:20:54.1137176Z"
}

Status Code	Meaning
400	Bad Request — Invalid request format or failed validation
401	Unauthorized — Missing or invalid authentication credentials
404	Not Found — The requested resource could not be found
422	Unprocessable Entity — Semantic errors in the request payload
500	Internal Server Error — An unexpected error occurred on the server

Best Practices

• Validate inputs before sending requests to avoid 400 errors
• Refresh tokens when you receive a 401 error
• Implement exponential backoff for retrying on 5xx errors
• Log the traceId from error responses when contacting support — it helps our team trace the exact request