Files

defiQUG 651ff4f7eb Initial project setup: Add contracts, API definitions, tests, and documentation

- Add Foundry project configuration (foundry.toml, foundry.lock)
- Add Solidity contracts (TokenFactory138, BridgeVault138, ComplianceRegistry, etc.)
- Add API definitions (OpenAPI, GraphQL, gRPC, AsyncAPI)
- Add comprehensive test suite (unit, integration, fuzz, invariants)
- Add API services (REST, GraphQL, orchestrator, packet service)
- Add documentation (ISO20022 mapping, runbooks, adapter guides)
- Add development tools (RBC tool, Swagger UI, mock server)
- Update OpenZeppelin submodules to v5.0.0

2025-12-12 10:59:41 -08:00

2.0 KiB

Raw Permalink Blame History

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

{
  "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

Always include reasonCode in error responses for transfer operations
Use requestId for correlation in logs
Provide actionable error messages
Include relevant context in details field

2.0 KiB Raw Permalink Blame History