Skip to main content

HTTP status codes and their handling

This page provides information on the errors that can occur when sending a request to the Tranzzo API.

Below is a general list of HTTP status codes and associated errors:

Error codeDescriptionRecommendations
400Bad RequestThis error occurs when the request parameters are incorrect or incomplete. To resolve it, ensure that the request parameters are accurate and complete.
401UnauthorizedThis error indicates that one or more authentication parameters (POS_ID, API_KEY, API_SECRET, ENDPOINTS_KEY) have an invalid value.
To fix it, verify the authentication values used and ensure that they are current.
404Not FoundThis error happens when the endpoint or payment record can't be found. To resolve it, check the URL correctness and make sure it's complete.
405Method Not AllowedThis error indicates that an unsupported HTTP method was used in the request. Verify the documentation requirements for the appropriate request type and HTTP method.
406Not AcceptableThis error occurs when the POST HTTP request doesn't contain application/json content in the required format. Ensure that the content is included in the appropriate format in the request.
429Too Many RequestsThis error indicates that too many requests were made in a short period. Wait for a short pause before retrying the request to avoid this error.
500Internal Server ErrorThis type of error refers to internal errors on the Tranzzo side. Contact Tranzzo Support for assistance in resolving the issue.
503Service UnavailableThis error indicates that the server is not available. Wait for a short pause and retry the request. If the error persists, please contact Tranzzo Support for assistance.

When a customer error occurs (indicated by a4ХХ status code), the response from the server will have the following structure:

FieldTypeRequired
messageString(512)
argsJSON
args.codeString(16)

Response example:

{
"message": "Invalid pos_id field or credentials",
"args": {
"code": "S-403"
}
}

Receiving an error with a 4ХХ status code in the response indicates that the payment has not been created or was created with an unsuccessful status. If you encounter a 404 status code, we recommend retrying the request.

The structure of a response that contains information about a server-side error (5ХХ status codes) is as follows:

FieldTypeRequired
messageString(512)
argsObject
args.error_idString(16)

Response example:

{
"message": "Internal error occurred",
"args": {
"error_id": "NYdKYdA4Zv3iOJSw"
}
}

The args parameter can also include the Obj field, which is a data array.

Response example:

{
"message": "Invalid values provided",
"args": {
"obj": [
{
"msg": [
"The card is expired: expiry month and year must be numbers that are gte than today"
],
"args": []
}
]
}
}

In certain cases, the args parameter can be transferred as a data array.

Response example:

{
"message":"Invalid amount provided",
"args":[
{
"field_name":"amount",
"violation":"Invalid value for 'amount': must be a Number in range of [500 - 100000] INR, actual - 300"
}
]
}

Upon receiving the 500 or 503 status codes, we recommend retrying the request for the transaction status update using the value of the order_id parameter set in the payment request. Please make the request no earlier than 1 minute after receiving the error messag

Another type of error is related to sending a request to a nonexistent endpoint.

Response example:

{
"code": 5,
"details": [
{
"@type": "type.googleapis.com/google.rpc.DebugInfo",
"detail": "service_control",
"stackEntries": []
}
],
"message": "Method does not exist."
}

Upon receiving the error above, we recommend verifying the accuracy of the endpoint address to which you sent the request.

The following errors may occur when requests are improperly structured:

Error messageRecommendation
API key not valid. Please pass a valid API key.Check the value of the ENDPOINTS_KEY parameter
Method doesn't allow unregistered callers (callers without established identity). Please use API Key or other form of API consumer identity to call this API.Ensure that the X-API-KEY header is included
Invalid pos_id field or credentialsEnsure that the values used for X-API-Auth and POS_ID parameters are correct and valid