# Errors

## **Introduction**

Unico IDPay uses conventional HTTP response codes to indicate the success or failure of an API request.

As a general rule:

* Codes in the 2xx range indicate success with the request.
* Codes in the 4xx range indicate incorrect or incomplete parameters (for example, a mandatory parameter was omitted, or an operation failed with third parties, etc.).
* Codes in the 5xx range indicate an error on the Unico IDPay product servers.

Unico IDPay also generates an error message and an error code formatted in JSON:

```json
{
    "error": {
        "code": "40004",
        "description": "transaction id is invalid"
    }
}
```

## Possible Errors

In this topic, you will find the possible errors for the endpoints, separated by their HTTP response.

### Transaction Creation

<table><thead><tr><th width="155">HTTP Code</th><th width="136">Code</th><th>Description</th><th>Reason</th></tr></thead><tbody><tr><td>400</td><td>40001</td><td>error decoding json</td><td>The data sent does not match the service contract.</td></tr><tr><td>400</td><td>40002</td><td>error validating json</td><td>Some information is poorly formatted or missing.</td></tr><tr><td>400</td><td>40021</td><td>invalid phone</td><td>The provided phone number is invalid, it must follow the format: 55 DDD NUMBER. For example: 5543999999999.</td></tr><tr><td>400</td><td>40022</td><td>invalid email</td><td>The provided email is invalid.</td></tr><tr><td>400</td><td>40027</td><td>replicated transaction</td><td>The transaction sent already exists and cannot be created again.</td></tr><tr><td>400</td><td>40045</td><td>max value reached</td><td>When the transaction reaches a value higher than the allowed limit.</td></tr><tr><td>403</td><td>40301</td><td>not allowed</td><td>The user does not have permission to perform this action.</td></tr><tr><td>404</td><td>40404</td><td>company not found</td><td>The provided company does not exist.</td></tr><tr><td>429</td><td>40001</td><td>too many requests</td><td>Rate limit reached.</td></tr><tr><td>500</td><td>50001</td><td>internal error</td><td>Internal service failure.</td></tr></tbody></table>

### Get transaction status

<table><thead><tr><th width="152">HTTP Code</th><th width="139">Code</th><th>Description</th><th>Reason</th></tr></thead><tbody><tr><td>400</td><td>40001</td><td>error decoding json</td><td>The data sent does not match the service contract.</td></tr><tr><td>400</td><td>40002</td><td>error validating json</td><td>Some information is poorly formatted or missing.</td></tr><tr><td>400</td><td>40004</td><td>transaction id is invalid</td><td>The transaction ID is invalid (format).</td></tr><tr><td>400</td><td>40301</td><td>not allowed</td><td>The user does not have permission to perform this action.</td></tr><tr><td>429</td><td>40401</td><td>transaction not found</td><td>The transaction was not found.</td></tr><tr><td>500</td><td>50001</td><td>internal error</td><td>Internal service failure.</td></tr></tbody></table>

### Recovery of the evidentiary set of the transaction

<table><thead><tr><th width="153">HTTP Code</th><th width="136">Código</th><th>Descrição</th><th>Motivo</th></tr></thead><tbody><tr><td>400</td><td>40004</td><td>transaction id is invalid</td><td>The transaction ID is invalid (format).</td></tr><tr><td>400</td><td>40009</td><td>transaction status is invalid</td><td>The transaction status is invalid (not allowed for generating the proof set).</td></tr><tr><td>403</td><td>40301</td><td>not allowed</td><td>The user does not have permission to perform this action.</td></tr><tr><td>404</td><td>40401</td><td>transaction not found</td><td>The transaction was not found.</td></tr><tr><td>500</td><td>50001</td><td>internal error</td><td>Internal service failure.</td></tr></tbody></table>

### Resending the transaction notification

<table><thead><tr><th width="150">HTTP Code</th><th width="142">Código</th><th>Descrição</th><th>Motivo</th></tr></thead><tbody><tr><td>400</td><td>40001</td><td>error decoding json</td><td>The data sent does not match the service contract.</td></tr><tr><td>400</td><td>40002</td><td>error validating json</td><td>Some information is incorrectly formatted or has not been filled out.</td></tr><tr><td>400</td><td>40004</td><td>transaction id is invalid</td><td>The transaction ID is invalid (format).</td></tr><tr><td>400</td><td>40009</td><td>transaction status is invalid</td><td>The transaction status does not allow notification resend (it is already completed).</td></tr><tr><td>400</td><td>40021</td><td>invalid phone</td><td>The phone number provided is invalid, it must follow the format: 55 DDD NUMBER. For example: 5543999999999.</td></tr><tr><td>400</td><td>40022</td><td>invalid email</td><td>The provided email is invalid.</td></tr><tr><td>403</td><td>40301</td><td>not allowed</td><td>The user does not have permission to perform this action.</td></tr><tr><td>404</td><td>40401</td><td>transaction not found</td><td>The transaction was not found.</td></tr><tr><td>429</td><td>40001</td><td>too many requests</td><td>Rate limit reached.</td></tr><tr><td>500</td><td>50001</td><td>internal error</td><td>Rate limit reached.</td></tr></tbody></table>

### Credit card onboarding

<table><thead><tr><th width="146">HTTP Code</th><th width="139">Código</th><th>Descrição</th><th>Motivo</th></tr></thead><tbody><tr><td>400</td><td>40001</td><td>error decoding json</td><td>The data sent does not match the service contract.</td></tr><tr><td>400</td><td>40002</td><td>error validating json</td><td>Some information is either incorrectly formatted or missing.</td></tr><tr><td>400</td><td>40027</td><td>replicated transaction</td><td>The submitted transaction already exists and cannot be created again.</td></tr><tr><td>400</td><td>40030</td><td>invalid identity</td><td>The CPF provided in the request differs from the CPF associated with the specified <code>processID</code>.</td></tr><tr><td>400</td><td>40045</td><td>max value reached</td><td>When the transaction exceeds the permitted amount.</td></tr><tr><td>400</td><td>40054</td><td>processID is invalid</td><td>When the <code>processID</code> provided in the request is invalid (or does not exist).</td></tr><tr><td>400</td><td>40055</td><td>processID is expired</td><td>When the <code>processID</code> being used is too old.</td></tr><tr><td>403</td><td>40301</td><td>not allowed</td><td>The user does not have permission to perform this action.</td></tr><tr><td>404</td><td>40404</td><td>company not found</td><td>The specified company does not exist.</td></tr><tr><td>404</td><td>40410</td><td>processID not found</td><td>When the specified process does not exist.</td></tr><tr><td>404</td><td>40412</td><td>image not found</td><td>When the process specified by the user does not have an image.</td></tr><tr><td>429</td><td>40001</td><td>too many requests</td><td>Rate limit reached.</td></tr><tr><td>429</td><td>42901</td><td>too many requests</td><td>When the client is sending too many requests, exceeding the predefined limit.</td></tr><tr><td>500</td><td>50001</td><td>internal error</td><td>Internal service failure.</td></tr></tbody></table>


---

# 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://devcenter.unico.io/unico-idpay/en/integration/apis/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.