# Error Handling

All errors from the ConnectPSP API return a standardized **RFC 7807 Problem Details** JSON object.

## Error Format


```json
{
  "type": "https://connect-psp.redocly.app/errors/insufficient-funds",
  "title": "Insufficient Funds",
  "status": 422,
  "code": "INSUFFICIENT_FUNDS",
  "detail": "The requested amount of R$ 500.00 exceeds available balance of R$ 100.00."
}
```

| Field | Description |
|  --- | --- |
| `type` | URI that identifies the error category. |
| `title` | Short, human-readable summary (stable across occurrences). |
| `status` | HTTP status code. |
| `code` | Machine-readable error code. **Use this for programmatic handling.** |
| `detail` | Human-readable explanation of this specific error occurrence. |


## HTTP Status Codes

| Status | When it occurs |
|  --- | --- |
| `400 Bad Request` | Invalid JSON, missing required field, or field validation failed. |
| `401 Unauthorized` | Missing, expired, or invalid JWT token or ApplicationToken. |
| `404 Not Found` | The requested transaction ID does not exist for this application. |
| `409 Conflict` | Duplicate `externalReference` on a Cash-Out request. |
| `422 Unprocessable Entity` | Business rule violation (see codes below). |
| `500 Internal Server Error` | Unexpected server error — contact support if it persists. |


## Error Codes Reference

### Authentication Errors

| Code | Status | Description |
|  --- | --- | --- |
| `INVALID_CREDENTIALS` | 401 | Wrong `clientId` or `clientSecret`. |
| `TOKEN_EXPIRED` | 401 | JWT token has expired. Re-authenticate via `POST /auth/token`. |
| `INVALID_APPLICATION_TOKEN` | 401 | `ApplicationToken` header is missing or does not match a valid integration. |
| `INVALID_SIGNATURE` | 422 | `DigitalSignature` header is missing or the HMAC hash is incorrect. |


### Cash-In Errors

| Code | Status | Description |
|  --- | --- | --- |
| `CASH_IN_NOT_PAID` | 422 | Refund attempted on a Cash-In that hasn't been paid yet. |
| `CASH_IN_ALREADY_REFUNDED` | 422 | Cash-In has already been refunded. |
| `CASH_IN_EXPIRED` | 422 | Cash-In has expired and received no payment. |
| `CASH_IN_CANCELLED` | 422 | Cash-In was cancelled. |
| `MISSING_END_TO_END_ID` | 422 | Cannot process refund — settlement proof (E2E ID) is not available yet. |


### Cash-Out Errors

| Code | Status | Description |
|  --- | --- | --- |
| `INSUFFICIENT_FUNDS` | 422 | Not enough funds in the transactional account to cover the withdrawal. |
| `PIX_KEY_NOT_FOUND` | 422 | The PIX key did not resolve to a valid bank account. |
| `DUPLICATED_EXTERNAL_REFERENCE` | 409 | A Cash-Out with this `externalReference` already exists. |
| `RULE_VIOLATION` | 422 | Generic business rule violation from the banking partner. |


### Account Errors

| Code | Status | Description |
|  --- | --- | --- |
| `INSUFFICIENT_PROPRIETARY_FUNDS` | 422 | Top-up failed — not enough funds in the Proprietary account. |
| `INSUFFICIENT_TRANSACTIONAL_FUNDS` | 422 | Sweep failed — not enough funds in the Transactional account. |
| `RETROACTIVE_BALANCE_NOT_IMPLEMENTED` | 422 | Historical balance lookup is not yet available. |
| `INVALID_AMOUNT` | 422 | Rebalance amount must be greater than zero. |


### General Errors

| Code | Status | Description |
|  --- | --- | --- |
| `NOT_FOUND` | 404 | Transaction not found for this application. |
| `VALIDATION_ERROR` | 400 | One or more request fields failed validation. Check `detail` for specifics. |


## Handling Errors in Code


```javascript
async function createCashOut(payload) {
  const response = await fetch('https://api.homologacao.connectpsp.com/cash-out', {
    method: 'POST',
    headers: { /* ... */ },
    body: JSON.stringify(payload)
  });

  if (!response.ok) {
    const error = await response.json();

    switch (error.code) {
      case 'INSUFFICIENT_FUNDS':
        // Notify operator that transactional balance is low
        await triggerRebalanceAlert();
        break;

      case 'DUPLICATED_EXTERNAL_REFERENCE':
        // Lookup existing transaction by externalReference
        const existing = await getCashOut(payload.externalReference);
        return existing;

      case 'PIX_KEY_NOT_FOUND':
        // Ask user to correct their PIX key
        throw new UserError('The PIX key provided is invalid.');

      default:
        // Log and escalate unknown errors
        logger.error('ConnectPSP error', error);
        throw new Error(error.detail);
    }
  }

  return response.json();
}
```