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	Outcome	Recommendations
400	Bad Request	❌ Final – failure	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	❌ Final – failure	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	❌ Final – failure	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	❌ Final – failure	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	❌ Final – failure	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	🔁 Retryable	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	⏳ Unknown – check status	This type of error refers to internal errors on the Tranzzo side. Contact Tranzzo Support for assistance in resolving the issue. Send a request for the transaction status update using the value of the order_id parameter that was set in the payment request.
503	Service Unavailable	⏳ Unknown – check status	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. Send a request for the transaction status update using the value of the order_id parameter that was set in the payment request.

caution

Receiving a 4XX status code error in response to a request indicates that the payment was either not created or was immediately created with a failed status. If a 404 status code is received, you may resend the request.

If a 500 or 503 status code is received, the transaction may have been successfully processed. We recommend sending a transaction status update request 1 minute after receiving the error.

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"
  }
}

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"
      }
   ]
}

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