General Error Model & Codes

Description

All payment services (

• /pws/paymentSet,
• /pws/payment,
• /pws/paymentOptions,
• /pws/payment/commit,
• /pws/payment/transaction,
• /pws/payment/cancel,
• /pws/payment/refund

share a common error model.

All responses returned from the services are provided in a standard JSON structure, along with an HTTP status code and an operation message, depending on the result of the transaction.

For failed operations, isSuccess = false is returned, and the errorCode and errorMessage fields specify the error details.

Some errors may appear both at the transaction level (data.errorCode) and at the service level (errors[]).

Response Structure

The basic response structure for all services is as follows:

{`  
  `"message": "Açıklama metni",`  
  `"statusCode": 400,`  
  `"exceptions": null,`  
  `"data": null,`  
  `"oldData": null,`  
  `"errors": [`  
    `{`  
      `"code": "P001",`  
      `"message": "Geçersiz istek parametresi"`  
    `}`  
  `]`  
`}`

Field Name	Type	Description
message	string	General information or error message
statusCode	int	HTTP status code (e.g. 200, 400, 401, 404, 500)
exceptions	object	Application-level captured exception (optional)
data	object	Successful operation response data
oldData	object	Previous record information in update scenarios
errors	array	May contain multiple error objects (with code and message fields)

Error Codes

Code	HTTP Status	Description	Example Scenario
P001	400	Invalid request parameter	Required fields are missing or sent in an invalid format
P002	401	Unauthorized access	Invalid or expired AccessToken
P003	403	Permission denied	User is not authorized to perform the operation
P004	404	Record not found	The reference code to be canceled/refunded does not exist
P005	409	Transaction conflict	Duplicate request sent for the same operation (e.g. double refund)
P006	422	Transaction validation error	Card number, BIN, or amount is invalid
P007	429	Too many requests	Too many requests sent in a short time
P008	500	System error	An unexpected server-side error occurred
P009	503	Bank service unavailable	Provisioning system or bank API is temporarily unavailable
P010	504	Timeout	Bank or payment gateway response timed out
P011	600	Payment failed	Bank declined the transaction (e.g. insufficient limit, 3D failure)
P012	601	OTP error	User authentication failed during the 3D Secure step
P013	602	Cancellation failed	The transaction to be canceled was not approved by the bank
P014	603	Refund failed	Refund request was rejected by the bank
P015	604	Partial refund limit exceeded	Total refund amount exceeds the original transaction amount
P016	605	Unsupported transaction type	Invalid transaction type specified in request parameters
P017	606	Transaction already completed	A transaction was resent with the same reference
P018	607	BIN undefined	The provided BIN number is not defined in the system
P019	608	POS not found	No valid POS definition exists in the relevant payment set
P020	609	Exchange rate error	Currency is not supported or exchange rate not found

Notes & Best Practices

• Operations returning StatusCode 200 are considered systemically successful. However, the transaction result received from the bank may have data.isSuccess=false.

• errorMessage is a short description that can be shown to the user. The exceptions field is intended only for error tracking/logging.

• For bank-related errors (P011–P015), detailed explanations are provided in the errorMessage field.

• For operations performed using referenceCode, invalid codes return a 404 - P004 error.

• During error handling, the client side should evaluate both statusCode and errorCode together.

• All error codes must remain fixed to ensure backward compatibility.