# Error Catalog

This document maps Solidity reason codes to HTTP status codes and provides error handling guidance.

## Reason Code to HTTP Status Mapping

| Reason Code | HTTP Status | Description |
|------------|-------------|-------------|
| `OK` | 200 | Operation successful |
| `PAUSED` | 503 | Token is paused |
| `FROM_FROZEN` | 403 | Source account is frozen |
| `TO_FROZEN` | 403 | Destination account is frozen |
| `FROM_NOT_COMPLIANT` | 403 | Source account not compliant |
| `TO_NOT_COMPLIANT` | 403 | Destination account not compliant |
| `LIEN_BLOCK` | 403 | Transfer blocked by active lien (hard freeze mode) |
| `INSUFF_FREE_BAL` | 403 | Insufficient free balance (encumbered mode) |
| `BRIDGE_ONLY` | 403 | Token in bridge-only mode |
| `NOT_ALLOWED_ROUTE` | 403 | Payment rail not allowed |
| `UNAUTHORIZED` | 401 | Unauthorized operation |
| `CONFIG_ERROR` | 500 | Configuration error |

## Standard Error Response Format

```json
{
  "code": "ERROR_CODE",
  "message": "Human-readable error message",
  "reasonCode": "PAUSED",
  "details": {
    "token": "0x1234...",
    "account": "0xabcd..."
  },
  "requestId": "uuid-here"
}
```

## Retry Rules

### Retryable Errors (5xx)
- `500` Internal Server Error - Retry with exponential backoff
- `503` Service Unavailable - Retry with exponential backoff
- `502` Bad Gateway - Retry with exponential backoff

### Non-Retryable Errors (4xx)
- `400` Bad Request - Do not retry, fix request
- `401` Unauthorized - Do not retry, refresh token
- `403` Forbidden - Do not retry, check permissions
- `404` Not Found - Do not retry, check resource ID
- `409` Conflict - Do not retry, check idempotency key

## Idempotency

Endpoints marked with `x-idempotency: true` accept an `Idempotency-Key` header. Requests with the same key within 24 hours return the same response without re-executing.

## Error Handling Best Practices

1. Always include `reasonCode` in error responses for transfer operations
2. Use `requestId` for correlation in logs
3. Provide actionable error messages
4. Include relevant context in `details` field