> For the complete documentation index, see [llms.txt](https://pivot-payment.gitbook.io/pivot-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://pivot-payment.gitbook.io/pivot-docs/api-references/api-information/errors.md).

# Errors

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

```json
{
    "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 <mark style="color:orange;">API\_ERROR</mark> or <mark style="color:orange;">GATEWAY\_ERROR</mark>

* <mark style="color:orange;">API\_ERROR</mark>: Either error is caused by a validation error or an invalid request. Usually will have an HTTP status <mark style="color:orange;">`4xx`</mark>
* <mark style="color:orange;">GATEWAY\_ERROR</mark>: Error is on Pivot Gateway side. You should expect this to rarely happen. Usually will have an HTTP status <mark style="color:orange;">`5xx`</mark>

#### Source

Error Source values will be one of <mark style="color:orange;">UPSTREAM</mark><mark style="color:orange;">, DOWNSTREAM, or SYSTEM</mark>

* <mark style="color:orange;">UPSTREAM</mark>: Errors caused by merchant request, configuration, or business rules
* <mark style="color:orange;">DOWNSTREAM</mark>: Errors caused by external dependencies
* <mark style="color:orange;">SYSTEM</mark>: 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 <mark style="color:orange;">`traceId`</mark>, then Pivot's system will generate the trace ID for you. You can use the <mark style="color:orange;">`traceId`</mark> when raising a helpdesk ticket to Pivot