# 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://pivot-payment.gitbook.io/pivot-docs/api-references/api-information/errors.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.