62 lines
2.0 KiB
Markdown
62 lines
2.0 KiB
Markdown
|
# 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
|
||
|
|
|