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 code	Description	Recommendations
400	Bad Request	This error occurs when the request parameters are incorrect or incomplete. To resolve it, ensure that the request parameters are accurate and complete.
401	Unauthorized	This 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.
404	Not Found	This 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.
405	Method Not Allowed	This error indicates that an unsupported HTTP method was used in the request. Verify the documentation requirements for the appropriate request type and HTTP method.
406	Not Acceptable	This 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.
429	Too Many Requests	This 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.
500	Internal Server Error	This type of error refers to internal errors on the Tranzzo side. Contact Tranzzo Support for assistance in resolving the issue.
503	Service Unavailable	This 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:

Field	Type	Required
message	String(512)	✅
args	JSON	✅
args.code	String(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:

Field	Type	Required
message	String(512)	✅
args	Object	✅
args.error_id	String(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 message	Recommendation
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 credentials	Ensure that the values used for X-API-Auth and POS_ID parameters are correct and valid