HTTP response codes

The Checkout API uses conventional HTTP response codes to indicate the success or failure of an API request. In general:

200: Request was successful.
4xx: This code range indicate an error that failed given the information provided (e.g., a required parameter was omitted).
5xx This code range indicate an error with the API's servers.

HTTP error response format

Requests that result in an error will return an HTTP status code in the 4xx or 5xx range. The body of the response will contain additional information. The JSON response format includes the following fields:

Field	Type	Description
`code`	`Number`	The three digit HTTP status code.
`details`	`Object`	Optional. This field may include additional information about the error and can be used for debugging.
`message`	`String`	A human-readable message providing more information about the error.
`timestamp`	`Number`	The date and time when the error occurred. This field is shown in Unix time.

HTTP error codes

Http Error code	OnlinePay Error code	Message	Details/redirection schema
400 Bad Request	107	At least one parameter is invalid. Examine the details property for more information. Invalid parameters are listed and prefixed accordingly: body for parameters submitted in the request's body, query for parameters appended to the request's URL, and params for templated parameters of the request's URL.	The request payload contains one or more parameters with an invalid format. Revise request payload and ensure that you have used the expected format for each field. For example: `body.amount:` should be a positive integer.
400 Bad Request	110	The submitted or requested resource is invalid. If you submitted a resource, please check for invalid fields, which will be listed in the details property. If you requested a resource, ensure the latter is valid, as well as its sub-resources.	Revise the request payload and ensure it's in proper JSON format (check for trailing commas, missing quotes, etc).
400 Bad Request	126	At least one parameter is missing from the request body. Revise request payload, API docs and refer to the integration guides for the payment methods to check for any conditionally required fields which might be necessary.	For example: `{ "missingParameters": ["body.amount"] }`
400 Bad Request	123	The transaction has been rejected by the processor. The request reached the processor, but it failed the validation checks required by the processor. Please examine your request. If the error persists, contact an administrator.	The payment has failed due to a technical failure in one of the upstream services involved in the payment. Please review additional details, which are stored in `checkout.eventsredirects` with query and reach out to OnlinePay Support teams for assistance parameter: `errorCode=123&checkoutId={checkoutId}`
400 Bad Request	127	At least one parameter is unexpected, or invalid. If you're trying to update a resource, be sure to include only parameters that you want to, and may, update. Some parameters are read-only or create-only.	For example: `{ "unexpectedParameters": ["parameterNotPresentInSchema"] }`
400 Bad Request	137	Parameters in the request body are conflicting with one another. It's likely that they are valid individually, yet they can't be submitted together, as that would lead to invalid combinations.	Please make sure the IDs inserted are correct. For example: `{ "parameters": ["entityId", "configurations.card.paymentContractId"], "reason": "The entityUid of the PaymentProviderContract(s) does not match the body.entityId" }`
400 Bad Request	166	The checkout you are trying to use has reached max notification attempts	-
400 Bad Request	167	Reached maximum theme creations allowed. Delete existing themes to create a new one	The maximum number of themes that can be created on an organization level is set to 15. To create an additional theme, you will have to delete an existing theme
401 Unauthorized	116	Access is restricted to authenticated users only. The query can't be made without a valid JWT (check the Authorization header of your request), or a valid session (in which case session cookies are automatically set by the browser).	For obtaining your authentication credentials, see Get started with the OnlinePay API
403 Forbidden	111	The submitted transaction has been blocked by a ruleset specified by the organization owning the account, or by a superior organization. Further information is available by querying the relevant ValidationRuleSetMatch, or by examining the blocked transaction in the user interface.	Redirects with query parameter as: `errorCode=111&checkoutId={checkoutId}&transactionId={transactionId}`
403 Forbidden	113	Insufficient permissions. Your current user roles don't allow you to perform this query. Should you believe this error to be incorrect, please contact an administrator	The roles of the user performing the request are not sufficient for the requested operation. Ensure that the user contains MERCHANT_SUPERVISOR or MERCHANT_CASHIER to be able to to create Checkouts. Ensure that MERCHANT_USER role is present if doing read operations.
403 Forbidden	121	The transaction has been declined by the processor. The request reached the processor, but it was not accepted. A decline reason code is available in the details property.	Redirects with query parameter: `errorCode=121&checkoutId={checkoutId}`. Please review additional details which are stored in `checkout.eventsredirects` with query and reach out to OnlinePay Support teams for assistance.
403 Forbidden	141	The checkout you are trying to use has already reached the maximum number of failed 3D secure processing attempts done through it and is not accessible anymore.	-
403 Forbidden	165	The checkout you are trying to use has already reached the maximum number of failed transaction attempts done through it and is not accessible anymore.	A Checkout link can be used three times to initiate a transaction. After the failed third request, a new link should be generated to place a transaction.
403 Forbidden	168	The checkout you are trying to use has already been completed.	Payment has already been completed using that specific checkout link In order to place a new transaction a new link must be generated. A payment link can only be used once for payments.
403 Forbidden	169	The checkout you are trying to use has expired.	The maximum value for a checkout link expiration time is 30 days
403 Forbidden	171	The checkout you are trying to use has been cancelled.	-
404 Not Found	109	The requested resource, or one of its sub-resources, can't be found. If the submitted query is valid, this error is likely to be caused by a problem with a nested resource that has been deleted or modified. Check the details property for additional insights.	One or more values in the request does not exist, or cannot be accessed by the user performing the request. Resource can vary, depending on which type of data cannot be found. `{ "resource": "Checkout", "id": "a6b45428-0296-4394-8ddd-0b50b5b20aa9" }`
500 Internal Server	100	Unexpected error: if the error persists, please contact an administrator, quoting the code and timestamp of this error	-
500 Internal Server	140	An error occurred during 3D Secure processing. For more information, please refer to the details property.	The payment has failed due to a technical failure in one of the upstream services involved in the payment. Please review additional details, which are stored in `checkout.eventsredirects` with query and reach out to OnlinePay Support teams for assistance.
500 Internal Server	170	Timeout of API call.	Please retry the API call. If the second request fails, reach out to OnlinePay Support teams for assistance.