> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getplu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Error codes and HTTP status codes returned by the API

## HTTP Status Codes

| Code  | Meaning               | When                                            |
| ----- | --------------------- | ----------------------------------------------- |
| `200` | Success               | GET, PATCH operations                           |
| `201` | Created               | POST operations that create resources           |
| `400` | Bad Request           | Validation failures, business logic errors      |
| `401` | Unauthorized          | Missing or invalid API key                      |
| `402` | Payment Required      | Insufficient wallet balance                     |
| `403` | Forbidden             | Suspended or pending partner account            |
| `404` | Not Found             | Resource doesn't exist or doesn't belong to you |
| `422` | Unprocessable Entity  | Request body validation errors                  |
| `429` | Too Many Requests     | Rate limit exceeded                             |
| `500` | Internal Server Error | Unexpected server error                         |

## Error Response Format

All errors follow this shape:

```json theme={null}
{
  "status": "error",
  "message": "ERROR_CODE",
  "data": {
    "error": "Human-readable description"
  }
}
```

## Error Codes

### User Errors

| Code                | HTTP | Description                                 |
| ------------------- | ---- | ------------------------------------------- |
| `DUP_USER`          | 400  | A user with this email already exists       |
| `USER_NOT_FOUND`    | 400  | The specified user service ID doesn't exist |
| `USER_NOT_APPROVED` | 400  | User hasn't completed KYC verification      |
| `USER_BLACKLISTED`  | 400  | User has been blacklisted                   |

### Card Errors

| Code                      | HTTP | Description                                             |
| ------------------------- | ---- | ------------------------------------------------------- |
| `CARD_NOT_FOUND`          | 404  | The specified card service ID doesn't exist             |
| `CARD_ALREADY_FROZEN`     | 400  | Card is already frozen                                  |
| `CARD_ALREADY_TERMINATED` | 400  | Card has been terminated and cannot be modified         |
| `CARD_IS_ACTIVE`          | 400  | Card is active (when trying to unfreeze an active card) |
| `CARD_CREATION_LIMIT`     | 400  | Only 1 card can be created per user every 5 minutes     |
| `CARD_DEBIT_LIMIT`        | 429  | Card debit rate limit exceeded                          |
| `INVALID_PROGRAM`         | 400  | Invalid card program for this operation                 |

### Wallet Errors

| Code                          | HTTP | Description                                        |
| ----------------------------- | ---- | -------------------------------------------------- |
| `INSUFFICIENT_WALLET_BALANCE` | 402  | Partner wallet doesn't have enough funds           |
| `INSUFFICIENT_FUNDS`          | 400  | Insufficient collateral balance for card operation |

### Transaction Errors

| Code                    | HTTP | Description                                |
| ----------------------- | ---- | ------------------------------------------ |
| `TRANSACTION_NOT_FOUND` | 404  | The specified transaction ID doesn't exist |

### General Errors

| Code                | HTTP | Description                         |
| ------------------- | ---- | ----------------------------------- |
| `PARTNER_NOT_FOUND` | 404  | Partner account not found           |
| `INTERNAL_ERROR`    | 500  | An unexpected server error occurred |

## Idempotency Errors

When using the `idempotency-key` header:

| Scenario                                 | HTTP | Message                               |
| ---------------------------------------- | ---- | ------------------------------------- |
| Same key + same body (duplicate request) | 400  | Idempotency key has already been used |
| Same key + different body                | 400  | Duplicate Idempotency key             |

## Validation Errors (422)

When request body validation fails, the response includes field-level errors:

```json theme={null}
{
  "status": "error",
  "message": "Validation failed",
  "data": {
    "error": [
      "firstName must be between 1 and 100 characters",
      "email must be a valid email address"
    ]
  }
}
```