Errors

Handling errors in Pivot's API

The error object explains the error details of your request. It is encapsulated as an error object in the response; if no error is found, then you should expect the error object to be omitted from the response.

Error Object

{
    "code": "human-readable code response",
    "message": "human-readable message response",
    "error": {      
        "type": "API_ERROR",
        "source": "UPSTREAM",      
        "details": [
            {
                "field": "email",
                "message": "Email is required"
            }
        ],      
        "trace_id": "ed9ef145530fc386190ddd7612ed61c7"
    },
    "data": { 
        // resource object
    }

The error object contains the following information:

Type

Error Type values will be one of API_ERROR or GATEWAY_ERROR

• API_ERROR: Either error is caused by a validation error or an invalid request. Usually will have an HTTP status 4xx

• GATEWAY_ERROR: Error is on Pivot Gateway side. You should expect this to rarely happen. Usually will have an HTTP status 5xx

Source

Error Source values will be one of UPSTREAM, DOWNSTREAM, or SYSTEM

• UPSTREAM: Errors caused by merchant request, configuration, or business rules

• DOWNSTREAM: Errors caused by external dependencies

• SYSTEM: Errors caused by Pivot infrastructure or internal services

Detail

Error details are exclusive to validation errors. You may expect it will contain an array of invalid fields.

Trace ID

ID to trace your request, if a request is not accompanied by traceId, then Pivot's system will generate the trace ID for you. You can use the traceId when raising a helpdesk ticket to Pivot