Response

Response Handling for Pivot's API

HTTP Status

Pivot uses standard and conventional HTTP Status Codes for each API Response given in a single API Request. In brief, the HTTP Status code 2xx indicates that the request is accepted and successfully processed by Pivot, 4xx indicating that the failure is caused by the information provided. (E.g., missing some required parameters, credentials are not valid). 5xx indicates that the error is on the Pivot side.

HTTP Status List used in Pivot API

HTTP Status	Description
200 OK	The request is successful
400 Bad Request	Format / missing fields
401 Unauthorized	Invalid API key / token
403 Forbidden	Feature not enabled / blocked
404 Not Found	Invalid reference ID
422 Unprocessable Entity	Valid request, invalid state
429 Too Many Requests	Merchant-specific guard
500 Internal Server Error	Bug / unexpected failure
502 Bad Gateway	Invalid response from downstream
503 Service Unavailable	Downstream downtime
504 Gateway Timeout	No response within SLA

Timeout

Pivot sets a default API timeout of 60 seconds. If the request takes longer than 60 seconds, then Pivot will return an HTTP code 408 for a timeout response.

Response Format

Response Format Example

{
    "code": "00",
    "message": "OK",
    "error": {      
        // error object
    },
    "data": { 
        // resource object
    },
    "pagination": { 
        "page": 2,
        "perPage": 20,
        "totalItems": 400,
        "totalPages": 20
    }
}

Pivot API returns a uniform response format, which helps you traverse the response easily. The payload contains the following information:

Parameter	Data Type	Requirement	Description
code	String	M	A code that represents the success or failure of your request. The List of response codes can be found in each section of API Services
message	String	M	A human-readable format that explains the response
error	Object	Conditional	An extended payload that explains the error in detail. See Errors
data	Object	Conditional	Contains the response data related with the accessed resources
pagination	Object	Conditional	Contains pagination information such as page number, how many records shows in page, total records, and total pages available