HTTP status codes and error handling

This page describes errors that may be returned when sending requests to the WhiteBoot API.

General list of HTTP status codes with errors:

Error code	Error description	Recommendations
400	Bad Request	This error means that the request is invalid. To resolve it, review the request parameters and make sure they are correct and complete.
401	Unauthorized	This error means that one or more authentication parameters (POS_ID, API_KEY, API_SECRET, ENDPOINTS_KEY) have an invalid or unacceptable value. Check the authentication values and use the current ones.
404	Not Found	The endpoint or payment record cannot be found. Check the URL used for the request. It may contain typos or may be missing part of the address.
405	Method Not Allowed	The request uses an unsupported HTTP method. Check the documentation requirements for the relevant request type and the HTTP method you are using.
406	Not Acceptable	A POST request must include application/json content. Include content in the required format in the request.
429	Too Many Requests	Too many requests were sent within a short period of time. Try sending the request again after a short pause.
500	Internal Server Error	This error refers to an internal error on the WhiteBoot side. Contact WhiteBoot support for more information about resolving the issue.
503	Service Unavailable	This error also refers to an internal error on the WhiteBoot side and means the server cannot be reached. Try sending the request again after a short pause. If that does not help, contact WhiteBoot support.

The response with client-side error information (4XX status codes) has the following structure:

Field	Type	Required
message	String(512)	✅
args	JSON	✅
args.code	String(16)

Example response:

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

Receiving a 4XX status code in response to a request means that the payment was not created or was immediately created with a failed status. If you receive a 404 status code, you can retry the request.

The response with server-side error information (5XX status codes) has the following structure:

Field	Type	Required
message	String(512)	✅
args	Object	✅
args.error_id	String(16)

Example response:

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

The args parameter may also contain the obj field, which is an array of data.

Example response:

{
   "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 some cases, the args parameter may also be returned as an array.

Example response:

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

When receiving a 500 or 503 status code, request the transaction status again using the order_id value that was set in the payment creation request. Request the transaction status no earlier than 1 minute after receiving the error.

Another error type may be returned when a request is sent to a nonexistent endpoint.

Example response:

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

If you receive this error, check that the endpoint address used for requests is correct.

Incorrectly formed requests may return the following errors:

Error message	Recommendation
API key not valid. Please pass a valid API key.	Check the ENDPOINTS_KEY parameter value.
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.	Check whether the X-API-KEY header is passed.
Invalid pos_id field or credentials	Check X-API-Auth and POS_ID.