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

# Errors

> Standard error responses, HTTP status codes, decimal handling, and idempotency across all PCX services

## Error response format

All PCX services return errors in a consistent JSON envelope:

```json theme={null}
{
  "status": "error",
  "message": "Human-readable description of what went wrong"
}
```

Some services include an additional `error` field with a technical detail string (present mainly on 500 responses):

```json theme={null}
{
  "status": "error",
  "message": "An internal error occurred",
  "error": "NullPointerException at use_case line 42"
}
```

***

## HTTP status codes

| Code  | Meaning               | When it occurs                                                                    |
| ----- | --------------------- | --------------------------------------------------------------------------------- |
| `200` | OK                    | Successful GET, PUT, PATCH, DELETE                                                |
| `201` | Created               | Successful POST that creates a resource                                           |
| `204` | No Content            | Successful DELETE with no response body                                           |
| `207` | Multi-Status          | Partial success (e.g. `target_type: both` notifications where one fails)          |
| `400` | Bad Request           | Missing required fields, invalid values, validation errors                        |
| `401` | Unauthorized          | Missing, malformed, or expired auth credentials                                   |
| `403` | Forbidden             | Valid credentials but insufficient role/permission                                |
| `404` | Not Found             | Resource does not exist                                                           |
| `409` | Conflict              | Operation conflicts with current state (e.g. duplicate invite, deletion conflict) |
| `500` | Internal Server Error | Unhandled exception in the service                                                |

***

## Success response format

Successful responses follow one of two shapes depending on the service:

**Standard envelope (most services):**

```json theme={null}
{
  "status": "success",
  "message": "Operation description",
  "data": { ... }
}
```

**Direct object (some older endpoints):**

```json theme={null}
{
  "user_id": "...",
  "email": "...",
  ...
}
```

***

## Decimal handling

Monetary values are stored as DynamoDB `Decimal` types and serialized to JSON as floats. Always treat amounts as `number` in your client — never as integers.